Portlets

BEA WebLogic
Portal A ™
ET
Portlet Development
Guide
B
Version 9.2 BETA

Document Revised: April 3, 2006
Copyright
Copyright © 1995-2006 BEA Systems, Inc. All Rights Reserved.
Restricted Rights Legend

This software is protected by copyright, and may be protected by patent laws. No copying or other use of this software is
permitted unless you have entered into a license agreement with BEA authorizing such use. This document is protected
by copyright and may not be copied photocopied, reproduced, translated, or reduced to any electronic medium or machine
readable form, in whole or in part, without prior consent, in writing, from BEA Systems, Inc.
Information in this document is subject to change without notice and does not represent a commitment on the part of BEA
Systems. THE DOCUMENTATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND INCLUDING
WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE. FURTHER, BEA SYSTEMS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
REPRESENTATIONS REGARDING THE USE, OR THE RESULTS OF THE USE, OF THE DOCUMENT IN
TERMS OF CORRECTNESS, ACCURACY, RELIABILITY, OR OTHERWISE.
Trademarks and Service Marks

A
Copyright © 1995-2006 BEA Systems, Inc. All Rights Reserved. BEA, BEA JRockit, BEA WebLogic Portal, BEA
ET
WebLogic Server, BEA WebLogic Workshop, Built on BEA, Jolt, JoltBeans, SteelThread, Top End, Tuxedo, and
WebLogic are registered trademarks of BEA Systems, Inc. BEA AquaLogic, BEA AquaLogic Data Services Platform,
BEA AquaLogic Enterprise Security, BEA AquaLogic Interaction, BEA AquaLogic Interaction Analytics, BEA
AquaLogic Interaction Collaboration, BEA AquaLogic Interaction Content Services, BEA AquaLogic Interaction Data
Services, BEA AquaLogic Interaction Integration Services, BEA AquaLogic Interaction Process, BEA AquaLogic
Interaction Publisher, BEA AquaLogic Interaction Studio, BEA AquaLogic Service Bus, BEA AquaLogic Service
Registry, BEA Builder, BEA Campaign Manager for WebLogic, BEA eLink, BEA Kodo, BEA Liquid Data for
WebLogic, BEA Manager, BEA MessageQ, BEA Salt, BEA WebLogic Commerce Server, BEA WebLogic
B
Communications Platform, BEA WebLogic Enterprise, BEA WebLogic Enterprise Platform, BEA WebLogic Enterprise
Security, BEA WebLogic Express, BEA WebLogic Integration, BEA WebLogic Java Adapter for Mainframe, BEA
WebLogic JDriver, BEA WebLogic Log Central, BEA WebLogic Mobility Server, BEA WebLogic Network
Gatekeeper, BEA WebLogic Personalization Server, BEA WebLogic Personal Messaging API, BEA WebLogic
Platform, BEA WebLogic Portlets for Groupware Integration, BEA WebLogic Real Time, BEA WebLogic RFID
Compliance Express, BEA WebLogic RFID Edge Server, BEA WebLogic RFID Enterprise Server, BEA WebLogic
Server Process Edition, BEA WebLogic SIP Server, BEA WebLogic WorkGroup Edition, BEA Workshop for WebLogic
Platform, BEA Workshop JSP, BEA Workshop JSP Editor, BEA Workshop Struts, BEA Workshop Studio, Dev2Dev,
Liquid Computing, and Think Liquid are trademarks of BEA Systems, Inc. Accelerated Knowledge Transfer, AKT, BEA
Mission Critical Support, BEA Mission Critical Support Continuum, and BEA SOA Self Assessment are service marks
of BEA Systems, Inc.
All other names and marks are property of their respective owners.
Contents
1. Introduction
Portlet Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Portlet Development and the Portal Life Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
A
Staging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
ET
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Related Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Part I. Architecture
2. Portlet Planning
B
Database Structure for Portlet Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Removing Portlets from Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Portlet Development in a Distributed Portal Team . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Portlets in a Non-Portal Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Planning Portlet Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Interportlet Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Performance Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
BEA WebLogic Portal Portlet Development Guide iii

3. Portlet Types
Java Server Page (JSP) and HTML Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Java Portlets (JSR 168) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Java Page Flow Portlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Java Server Faces (JSF) Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Browser (URL) Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Struts Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Remote Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Portlet Type Summary Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Part II. Development

4. Understanding Portlet Development A
Resources for Creating Portlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
ET
Portlet Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Portlet Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Portlet Title Bar, Mode, and State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Portlet Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Portlet Resources in the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
B
Types of Database Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

Management of Portlet Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
How the Database Shows Removed Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Portlet Rendering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
Render and Pre-Render Forking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
Asynchronous Portlet Content Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
Portlets as Popups (Detached Portlets) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
JSPs, JSP Tags, and Controls in Portlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
Backing Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
iv BEA WebLogic Portal Portlet Development Guide

5. Building Portlets
Portlets in Library Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
Third-Party Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Autonomy Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Documentum Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
MobileAware Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Portlet Wizard Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Order of Creation - Resource or Portlet First . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Starting the Portlet Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
New Portlet Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
A
Select Portlet Type Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
Portlet Details Dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
How to Build Each Type of Portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
ET
JSP and HTML Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
Java Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
Java Page Flow Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17
JSF Portlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20
Browser Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-23
B
Struts Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26

Remote Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26
Web Service Portlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-27
Detached Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-27
Considerations for Using Detached Portlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-27
Building Detached Portlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-28
Special Considerations When Building Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-28
6. Refining and Testing Portlets

Portlet Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
BEA WebLogic Portal Portlet Development Guide v

Editing Portlet Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Tips for Using the Properties View in the Workbench. . . . . . . . . . . . . . . . . . . . . . . . 6-3
Portlet Properties in the Portal Properties View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4
Portlet Properties in the Portlet Properties View . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
Portlet Preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16
Specifying Portlet Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-18
Using the Preferences API to Access or Modify Preferences . . . . . . . . . . . . . . . . . 6-23
Portlet Preferences SPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-28
Best Practices in Using Portlet Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30
Portlet Appearance and Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-32
Portlet Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-32
A
Portlet Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-35
Portlet States. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-38
ET
Portlet Title Bar Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-39
Portlet Height and Scrolling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-39
JSPs, JSP Tags, and Controls in Portlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-42
JSP and JSP Tags in Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-43
Portal Controls Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-44
B
Portlet Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-44

Event Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-45
Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-45
Event Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-46
Portlet Event Handlers Wizard Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-47
Error Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-51
Portlet State Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-51
Adding a Portlet to a Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-52
Removing and Deleting Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-54
vi BEA WebLogic Portal Portlet Development Guide

7. Optimizing Portlet Performance
Performance-Related Portlet Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Portlet Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Remote Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
How Remote Portlets Provide a Performance Boost . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Parallel Portlet Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Pre-Render Forking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Render Forking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
Asynchronous Portlet Content Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Considerations for IFRAME-based Aynchronous Rendering . . . . . . . . . . . . . . . . . . 7-7
A
Considerations for AJAX-based Asynchronous Rendering . . . . . . . . . . . . . . . . . . . . 7-7
Comparing IFRAME- and AJAX-based Aynchronous Rendering . . . . . . . . . . . . . . 7-8
Portal Life Cycle Considerations with Asynchronous Content Rendering . . . . . . . . 7-8
ET
Asynchronous Content Rendering and IPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9
Backing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10
How Backing Files are Executed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11
Thread Safety with Backing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13
Backing File Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13
B
Adding a Backing File to a Portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14
8. Interportlet Communication
IPC with Multiple Web Projects and IFRAMEs-Examples . . . . . . . . . . . . . . . . . . . . . . . 8-2
Before You Begin - Environment Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Basic IPC Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4
IPC Example with Custom and Page Flow Event Handlers. . . . . . . . . . . . . . . . . . . 8-17
IPC Special Considerations and Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17
Using Asynchronous Portlet Rendering with IPC . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17
Generic Event Handler for WSRP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18
BEA WebLogic Portal Portlet Development Guide vii

Consistency of the Listen To Field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18
Using a Session Attribute Instead of Request Attribute . . . . . . . . . . . . . . . . . . . . . 8-18
Part III. Staging

9. Assembling Portlets into Desktops
Portlet Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Portlets in the Library Compared with Portlets on the Desktop (decoupling). . . . . 11-2
Adding, Arranging, and Deleting Portlets on the Desktop . . . . . . . . . . . . . . . . . . . . . . . 11-2
Add a Portlet to a Page in the Staging Environment . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Move a Portlet on a Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Customizing Portlet Properties and Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5
A
Modify Portlet Properties in a Staging Environment. . . . . . . . . . . . . . . . . . . . . . . . 11-5
10.Deploying Portlets
ET
Deploying a New Portlet into a Production Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1
Part IV. Production

11.Managing Portlets in Production
B
Transferring Changes from Production Back to Development . . . . . . . . . . . . . . . . . . . . 13-1
viii BEA WebLogic Portal Portlet Development Guide

CHAPTER 1
Introduction
This chapter includes the following sections:
z Portlet Overview
A
This chapter introduces portlet concepts and describes the content of this guide.
ET
z Portlet Development and the Portal Life Cycle
Portlet Overview
Portlets are modular panes within a web browser that surface applications, information, and
business processes. Portlets can contain anything from static HTML content to Java controls to
B
complex web services and process-heavy applications. Portlets can communicate with each other
and take part in Java page flows that use events to determine a user’s path through an application.
A single portlet can also have multiple instances—in other words, it can appear on a variety of
different pages within a single portal, or even across multiple portals if the portlet is enabled for
Web Services for Remote Portlets (WSRP). You can customize portlets to meet the needs of
specific users or groups.
Figure 1-1 and Figure 1-2 provide examples of portlets that are included as samples with
WebLogic Portal. Figure 1-1 shows the view of the portlet as displayed in Workshop for
WebLogic; Figure 1-2 shows the view of the portlet in a web page.
BEA WebLogic Portal Portlet Development Guide 1-1

Introductio n
Figure 1-1 Sample Portlet in Workshop for WebLogic
Figure 1-2 Sample Portlet as Displayed in a Web Page
A
WebLogic Portal supports the development of portlets through BEA Workshop for WebLogic
Platform (Workshop for WebLogic), which is a client-based tool. You can develop portals
ET
without Workshop for WebLogic through coding in any tool of choice such as JBuilder, VI or
Emacs; portlets can be written in Java or JSP, and can include JavaScript for client-side
operations. However, to realize the full development-time productivity gains afforded to the
WebLogic Portal customer, you should use Workshop for WebLogic as your portal and portlet
development platform.
For a description of each type of portlet that you can build using WebLogic Portal, refer to
B
“Portlet Types” on page 3-1.
Portlet Development and the Portal Life Cycle

The tasks in this guide are organized according to the portal life cycle, which includes best
practices and sequences for creating and updating portals. For more information about the portal
life cycle, refer to the BEA WebLogic Portal Overview. The portal life cycle contains four phases:
architecture, development, staging, and production. Figure 1-3 shows a sampling of portlet
development tasks that occur at each phase.
1-2 BEA WebLogic Portal Portlet Development Guide

P o r t l e t D e v e l o p m e nt a nd t he Por t al L i f e C y c l e
Figure 1-3 Portlets and the Four Phases of the Portal Life Cycle
Architecture –
Plan the basic configuration
of the portal
Production –
Roll out your portlets, Development –
either individually or Use Workshop for
within the entire portal, WebLogic to create
to a production portlets, pages, and
environment, making books
changes as needed
Staging – A
Use the WebLogic Portal
Administration Console to
ET
create and configure desktops
Architecture
During the architecture phase, you plan the configuration of your portal. For example, you can
create a detailed specification outlining the requirements for your portal, the specific portlets you
B
require, where those portlets will be hosted, and how they will communicate and interact with one
another. You also consider the deployment strategy for your portal. Security architecture is
another consideration that you must keep in mind at the portlet level.
The chapters describing tasks within the architecture phase include:
z Chapter 2, “Portlet Planning”
z Chapter 3, “Portlet Types”
Development
Developers use Workshop for WebLogic to create portlets, pages, and books. During
development, you can implement data transfer and interportlet communication strategies.

Introductio n
In the development stage, careful attention to best practices is crucial. Wherever possible, this
guide includes descriptions and instructions for adhering to these best practices.
The chapters describing tasks within the development phase include:
z Chapter 4, “Understanding Portlet Development”
z Chapter 5, “Building Portlets”
z Chapter 6, “Refining and Testing Portlets”
z Chapter 7, “Optimizing Portlet Performance”
z Chapter 8, “Interportlet Communication”
Staging
A
BEA recommends that you deploy your portal, including portlets, to a staging environment,
where it can be assembled and tested before going live. In the staging environment, you use the
WebLogic Portal Administration Console to assemble and configure desktops. You also test your
portal in a staging environment before propagating it to a live production system. In the testing
ET
aspect of the staging phase, there is tight iteration between staging and development until the
application is ready to be released.
The chapters describing tasks within the staging phase include:
z Chapter 9, “Assembling Portlets into Desktops”
z Chapter 10, “Deploying Portlets”

B
Production
A production portal is live and available to end users. A portal in production can be modified by
administrators using the WebLogic Portal Administration Console and by users using Visitor
Tools. For instance, an administrator might add additional portlets to a portal or reorganize the
contents of a portal.
The chapter describing tasks within the production phase is:
z Chapter 11, “Managing Portlets in Production”

G e tt i n g S ta r te d
Getting Started
This section describes the basic prerequisites to using this guide and lists guides containing
related information and topics.
Prerequisites
In general, this guide assumes that you have performed the following prerequirsite tasks before
you attempt to use this guide to develop portlets:
z Review the Related Guides and become familiar with the basic operation of the tools used
to create portals, portlets, and desktops,
z Review the Workshop for WebLogic tutorials and documentation to become familiar with
the Eclipse-based developmnent environment and the recommended project hierarchy.
Related Guides
A
Complete the tutorial Getting Started with WebLogic Portal.
ET
BEA recommends that you review the following guides:
z BEA WebLogic Portal Architecture Guide
z BEA WebLogic Portal Overview
z BEA WebLogic Portal Portal Development Guide

Whenever possible, this guide includes cross references to material in related guides.
B

Introductio n
A
ET
B

Part I Architecture
A
During the architecture phase, you plan the configuration of the portlets that comprise your portal.
For a view of how the tasks in this section relate to the overall portal life cycle, refer to the BEA
WebLogic Portal Overview.
ET
B
Part I includes the following chapters:
z Chapter 2, “Portlet Planning”
z Chapter 3, “Portlet Types”
BEA WebLogic Portal Portlet Development Guide

A
ET
B

CHAPTER 2
Portlet Planning
A
Proper planning is essential to portlet development. A properly planned portlet structure and
organizational model can provide a cohesive and consistent portal interface, flexible scalability,
and high performance without requiring frequent adjustments within your production system.
This chapter focuses on planning considerations and decisions that should precede the
ET
development of your portlets. Global portal-wide planning information is provided in the BEA
WebLogic Portal Overview, which summarizes the types of issues to consider in the architecture
phase across your portal environment. The WebLogic Portal Architecture Guide includes more
detailed architectural guidance, guiding you through domain- and application-level issues. The
various WebLogic Portal feature guides, such as the BEA WebLogic Portal Federated Portals
Guide, describe architectural issues in detail for each feature area.
B
z Database Structure for Portlet Data
z Portlet Development in a Distributed Portal Team
z Portlets in a Non-Portal Environment
z Planning Portlet Instances
z Security
z Interportlet Communication
z Performance Planning

Po rt l e t P l a nn i ng
Database Structure for Portlet Data

When a portlet’s data is loaded into the database, the portlet XML is parsed and a number of
tables are populated with information about the portlet, including PF_PORTLET_DEFINITION,
PF_MARKUP_DEFINITION, PF_PORTLET_INSTANCE, PF_PORTLET_PREFERENCE,
L10N_RESOURCE, and L10N_INTERSECTION.
PF_PORTLET_DEFINITION is the master record for the portlet and contains rows for properties
that are defined for the portlet, such as the definition label, the forkable setting, edit URI, help
URI, and so on. The definition label and web application name are the unique identifying records
for the portlet. Portlet definitions refer to the rest of the actual XML for the portlet that is stored
in PF_MARKUP_DEF.
PF_MARKUP_DEF contains stored tokenized XML for the .portlet file. This means that the
.portlet XML is parsed into the database and properties are replaced with tokens. For example,
the following code fragment shows a tokenized portlet:
A
<netuix:portlet $(definitionLabel) $(title) $(renderCacheable)
$(cacheExpires)>
ET
These tokens are replaced by values from the master definition table in
PF_PORTLET_DEFINITION, or by a customized instance of the portlet stored in
PF_PORTLET_INSTANCE.
The following four types of portlet instances are recorded in the database for storing portlet
properties:
z Primary – Properties defined in development and stored in the .portlet file.

B
z Library – Properties defined in the Portal Library, which may be changed using the
WebLogic Administration Portal.
z Admin – A customized instance of the portlet in a desktop. This allows you to customize a
portlet in a particular way for a desktop without affecting other instances of the portlet in
other desktops.
z User – User-customized instances of the portlet defined in the Visitor Tools.

PF_PORTET_INSTANCE contains properties for the portlet for attributes such as
DEFAULT_MINIMIZED, TITLE_BAR_ORIENTATION, and PORTLET_LABEL.
If a portlet has portlet preferences defined, those are stored in the PF_PORTLET_PREFERENCE
table.

Po rtlet Dev elopment in a D i s tr i b ut e d P o rt a l T e am
Finally, portlet titles can be internationalized. Those names are stored in the L10N_ RESOURCE
table which is linked using L10N_INTERSECTION to PF_PORTLET_DEFINITION.
Removing Portlets from Production

If a portlet is removed from a newly deployed portal application and it has already been defined
in the production database, it is marked as IS_PORTLET_FILE_DELETED in the
PF_PORTLET_DEFINITION table. It displays as grayed out in the WebLogic Administration
Portal, and user requests for the portlet, if it is still contained in a desktop instance, return a
message indicating that the portlet is unavailable.
Portlet Development in a Distributed Portal Team

If you will be creating portlets within an environment that includes a remote (distributed)
development team, you must carefully plan your implementation. Considerations for team
development include:
z
A
Using shared resources – You can have common portlets, such as the login portlet.
ET
z Sharing a common domain – You can have a common domain among team members
with different BEA home directories.
z Integrating remotely developed portlets into the portal – You need to manage settings
that are common to the portal application, which must match across the entire development
project.
Team development of a WebLogic Portal web site revolves around well-designed source control
B
and a correctly configured shared domain for development. For detailed instructions on setting
up your development environment, refer to the Team Development chapter of the BEA WebLogic
Portal Production Operations User’s Guide.
Portlets in a Non-Portal Environment

In some cases, you might want to expose portlets in a web page even though that web application
is not based on WebLogic Portal. The term commonly given to this process is “portletizing.”
For example, you might want to expose portlets with WSRP from a producer environment that
does not include any WebLogic Portal components. You might be running a Struts web
application in a basic WebLogic Server domain, or a Java page flow application in a basic
Workshop for WebLogic domain. In either case, WebLogic Portal is not part of the server

configuration. The exposed portlets can then be consumed by remote portlets running in a regular
WebLogic Portal domain.
When you choose to implement portlets in a non-WebLogic Portal environment, keep the
following considerations in mind:
z Session information is not retained - TBD
Planning Portlet Instances

In the staging phase of development, you use the Administration Console to add portlets to portal.
Each time you add a portlet to a portal, you create an instance of that portlet. Portlet instances
allow for multiple variations of the same portlet definition. By using portlet instances, portal users
and administrators can configure multiple views of the same portlet through the use of portlet
preferences, and reduce the overall number of distinct portlets; this portlet reuse improves portal
A
performance and management efficiency. A common example of portlet instances is a stock
watch portlet in which there is a single or multi-valued preference for ticker symbols such as
BEAS, which would configure the portlet to display BEA Systems stock information.
Try to plan your portal hierarchy to reuse portlets when practical. For more information about
ET
portlet instances and how portlet instances are related to portlets in the Administration Console’s
portlet library, refer to <link>.
Security
You can control access to portlet resources for two categories of users:
B
z Portal visitors – You control access to portal resources using visitor entitlements. Visitor
access is determined based on visitor entitlement roles.
z Portal administrators – You control portal resource management capabilities using

delegated administration. Administrative access is determined based on delegated
administration roles.
During the architecture phase, you plan how to organize security policies and roles, and how that
fits into your system-wide security strategy. For an overall look at managing security for your
portal environment, refer to the BEA WebLogic Portal Security Guide. Specific security
considerations for feature areas are contained in those documents; for example, recommendations
for security in WSRP-enabled environments are contained in the BEA WebLogic Portal
Federated Portals Guide.

I nt e r po rt l e t C o mmu ni c at i o n
Interportlet Communication
Interportlet communication (IPC) allows multiple portlets to use or react to data. You can use
interportlet communication within a single portal web application, or within federated portal
applications.
When you choose to implement interportlet communication within a single portal web
application, keep the following considerations in mind:
z Team development - If you plan to use event handlers, your developers must coordinate
the use of events and event actions.
For more information on interportlet communication within a single portal web application, refer
to Chapter 7, “Interportlet Communication.” For more information on interportlet
communication within federated portal applications, refer to the BEA WebLogic Portal
Performance Planning A
Try to plan for good performance within your portlet architecture to minimize the fine-tuning that
ET
is required in a production environment.
Here are some examples of performance optimizations that you can plan into your overall portal
strategy:
z Portlet caching – You can cache the portlet within a session instead of retrieving it each
time it recurs during a session (on different pages, for example).
B
z Remote portlets – With remote portlets, any controls within the application (portlet) that
you are retrieving are rendered by the producer and not by your portal. The expense of
calling the control life cycle methods is borne by resources not associated with your portal.
z Customized portlet properties – Customizing your portlet settings can help you improve
performance; for example, you can set process-expensive portlets to pre-render or to render
in a multi-threaded (forkable) environment.
z Backing files – Backing files allow you to programmatically add functionality to a portlet
by implementing (or extending) a Java class, which enables pre-processing (for example,
authentication) prior to rendering the portal controls.
Plan your performance optimizations before you begin developing portlets so that you can
implement any pre-requisites that are required. For detailed instructions on developing
high-performance portlets, refer to Chapter 7, “Optimizing Portlet Performance.” For

post-development WebLogic Portal performance recommendations, refer to the BEA WebLogic

Portal Performance Tuning Guide (available post-GA).
A
ET
B

CHAPTER 3
Portlet Types
A
As part of your portlet implementation plan, BEA recommends that you examine the different
types of portlets that are available in WebLogic Portal and decide which types are best suited for
the tasks that you want to accomplish. For example, if you are looking for a way to interface with
Java controls, use Struts-based infrastructure, and deliver rich navigation elements, then you
ET
might choose to implement Java Page Flow portlets. If you are looking for a simple portlet or you
want to convert an existing JSP page into a portlet, you might consider using a JSP portlet. If you
work for an independent software company or other enterprise that is concerned with portability
across multiple portals, then you might choose to use JSR 168-compliant Java portlets whenever
possible. If you want to implement asynchronous portlet rendering in your portal, you can use
nearly any of the portlet types described in this chapter.
B
This chapter differentiates the various portlet types to help you in your decision-making process.
This chapter contains the following sections:
z Java Server Page (JSP) and HTML Portlets
z Java Portlets (JSR 168)
z Java Page Flow Portlets
z Java Server Faces (JSF) Portlets
z Browser (URL) Portlets
z Struts Portlets
z Remote Portlets

Po rt let T yp es
z Portlet Type Summary Table
Java Server Page (JSP) and HTML Portlets

JSP portlets and HTML portlets point to JSP or HTML files for their content. These portlets can
be simple to implement and deploy, and they provide basic functionality quickly. However, this
type of portlet does not enforce separation of business logic and the presentation layer. As the
application grows, the portlet often becomes harder to maintain as you try to update the web
application and share code. JSP portlets are not well-suited for advanced portlet navigation.
When using JSP portlets as part of a Page Flow, you must make sure that requests adhere to
WebLogic Portal scoping requiremetns. For more information about JSP portlets and Page Flow
scoping, refer to the Portal Development Guide.
For instructions on building JSP portlets, see “JSP and HTML Portlets” on page 5-11.
Java Portlets (JSR 168) A

JSR 168 (Java Portlet) is a Java specification that aims at establishing portability between portlets
ET
and portals. One of the main goals of the specification is to define a set of standard Java APIs for
portal and portlet vendors. These APIs cover areas such as presentation, aggregation, security,
and portlet life cycle.
The output of a JSR 168-compliant portlet is a Java file. This type of portlet accommodates
portability across platforms, and does not require the use of portal server-specific JSP tags. The
behavior is similar to a servlet. For details, refer to “Developing JSR 168 Portlets with WebLogic
Portal 8.1" (http://dev2dev.bea.com/pub/a/2004/02/JSR168.html) on the BEA dev2dev site . JSR
B
168 portlets produced using WebLogic Portal can be used universally by any other vendor’s
application server container.
Java portlets are best suited for an environment where portability across multiple portlet
containers is most important. Current disadvantages include a lack of access to advanced portlet
features that are available with some other portlet types , and the requirement for a deeper
understanding of the J2EE programming model to implement them.
For instructions on building Java portlets, refer to “Java Portlets” on page 5-12.

Java Page Fl ow Portlets
Java Page Flow Portlets

A Java page flow portlet uses page flows to retrieve its content. This portlet type allows you to
separate the user interface code from navigation control and other business logic, and provides
the ability to implement both simple and advanced portlet navigation.
The page flow framework that is recommended for portlet application development is built on top
of the Struts application framework. The Struts framework is a popular, reliable standard that is
widely used to quickly create robust and navigable web applications. The page flow framework
adds valuable data binding facilities to the Struts standard, and the portal framework provides a
scoping capability for page flow portlets so that multiple page flows can be supported in a single
portal. You can use resources such as Java controls and web services.
Java page flow portlets are best suited for an environment where more advanced features are
required—not for static, single-view portlets.
page 5-17.
Java Server Faces (JSF) Portlets

A
For instructions on building Java page flow portlets, refer to “Java Page Flow Portlets” on
ET
The Java Server Faces (JSF) specification, JSR 127, defines a user interface framework that
simplifies development and maintenance of Java applications that run on a server and are
displayed and used from a client.
According to the Java Server Faces Specification, available from the Java Community Process
web site:
B
JSF’s core architecture is designed to be independent of specific protocols and markup. However
it is also aimed directly at solving many of the common problems encountered when writing
applications for HTML clients that communicate via HTTP to a Java application server that
supports servlets and JavaServer Pages (JSP) based applications. These applications are typically
form-based, and are comprised of one or more HTML pages with which the user interacts to
complete a task or set of tasks. JSF tackles the following challenges associated with these
applications:
z Managing UI component state across requests
z Supporting encapsulation of the differences in markup across different browsers and clients
z Supporting form processing (single multi-page form, or more than one form per page)

Po rt let T yp es
z Providing a strongly typed event model that allows the application to write server-side
handlers (independent of HTTP) for client generated events
z Validating request data and providing appropriate error reporting
z Enabling type conversion when migrating markup values (Strings) to and from application
data objects (which are often not Strings)
z Handling error and exceptions, and reporting errors in human-readable form back to the
application user
z Handling page-to-page navigation in response to UI events and model interactions.

For instructions on building Java Server Faces portlets, refer to “JSF Portlets” on page 5-20.
Browser (URL) Portlets

A
Browser portlets are basically HTML portlets that display an external URL. Unlike other portlet
types that are limited to displaying data contained within the portal project, browser portlets
display URL content that is external from the portal project.
ET
An advantage of browser portlets is that no development tasks are required to implement it, either
from the Workshop for WebLogic workbench or from the WebLogic Portal Administration
Console. However, keep in mind that WebLogic Portal does not provide a mechanism to develop
content for this type of portlet; the definition of the portlet merely contains the external URL to
display. For example, no mechanisms exist to dynamically influence the external content’s URL;
no support exists for portlet preferences, portlet modes, and so on. Browser portlets do not track
the URL through the user’s interaction with remote content – page refreshes cause the content of
B
the URL specified in the portlet definition to be displayed.

WebLogic Portal implements a browser portlet using an IFRAME. You can override the default
implementation mechanism using more advanced development techniques; more detailed
documentation about these techniques will be provided in a future dev2dev article.
The content of the browser portlet is completely disconnected from the portal. The embedded
application must manage the navigational state of the portlet.
For instructions on building Browser portlets, refer to “Browser Portlets” on page 5-23.
Struts Portlets
Struts portlets are based on the Struts framework, which is an implementation of the
Model-View-Controller (MVC) architecture. The MVC architecture provides a model for

R e m o t e Por t l e t s
separating the different components and roles of the application logic. This development
framework helps you create portlets that are easier to maintain over time.
Typically, native Struts development requires management and synchronization of multiple files
for each action, form bean, as well as the Struts configuration file. Even in the presence of tools
that help edit these files, developers are still exposed to all the underlying plumbing, objects, and
configuration details. The WebLogic Portal implementation provides a simpler, single-file
programming model that allows developers to focus on the code they care about, see a visual
representation of the overall application flow, and navigate between pages, actions, and form
beans.
For instructions on building Struts portlets, refer to “Struts Portlets” on page 5-26.
Remote Portlets
A
WebLogic Portal supports the Web Services for Remote Portlets (WSRP) standard, a product of
the OASIS standards body. Portlets that are written to meet this standard, which includes a
WSDL portlet description, can be hosted within a producer application, and surfaced in a
consumer application. Moreover, the WebLogic Portal Administration Console facilitates access
ET
to WSRP producer applications in a local portal.
WebLogic Portal’s remote—or proxy—portlets are WSRP-compliant. These portlets present
content that is collected from WSRP-compliant producers, allowing you to use external sources
for portlet content, rather than having to create its content or its structure yourself.
Because setting up a remote portlet is a fundamental task in creating a federated portlet

B
environment, the task of creating a remote portlet is described in detail within the BEA WebLogic
Portal Federated Portals Guide.
Portlet Type Summary Table

Table 3-1 summarizes the characteristics of each portlet type so that you can quickly determine
the advantages and disadvantages of each type.

Po rt let T yp es
Table 3-1 Portlet Type Summary Table

Type Advantages Disadvantages
JSP/HTML Simple to implement and deploy. Does not enforce separation of business logic
Provides basic functionality without and presentation layer.
complexity. Not well-suited for advanced portlet
navigation.
Java Accommodates portability across Lack of advanced portlet features that are
platforms. available with some other portlet types.
Does not require the use of portal Requires a deeper understanding of the J2EE
server-specific JSP tags. programming model.
Behavior is similar to a servlet
Java Page Flow Simplifies separation of the user interface

code from navigation control and other
business logic.
Provides the ability to implement both
A
Implementation is more complex.
Advanced page flow features are not necessary
for static or simple, one view portlets.
ET
simple and advanced portlet navigation.
Allow you to quickly leverage Java
controls, web services, and business
processes.
Provides a visual environment to build
rich applications based on struts.
JSF Allows component-based development of All postbacks to a JSF application are expected
B
pages that can handle their own intra-page to be done using a POST; the GET method is
events. not supported.
Simplifies separation of the user interface
code from navigation control and other
business logic.
Provides the ability to implement both
simple and advanced portlet navigation.
Allow you to quickly leverage Java
controls, web services, and business
processes.
Browser Allows a portlet to display content from a Lacks certain features of other portlet types,
URL that is outside the portal project. such as Content Path and Error Path.

P o r t l e t T y p e S um m ar y T ab l e
Table 3-1 Portlet Type Summary Table (Continued)

Struts Provides a flexible control layer based on

standard technologies like Java Servlets,
JavaBeans, ResourceBundles, and XML.
Provides a more structured approach for
creating and maintaining complex
applications.
Remote Allows you to leverage external sources Implementation is more complex.

for portlet content.
A
ET
B

Po rt let T yp es
A
ET
B

Part II Development
A
During the development phase, you use Workshop for WebLogic to create portlets, pages, and
books. During development, you can implement federation and interportlet communication
strategies. In the development stage, careful attention to best practices is crucial.
ET
.
B
Part II includes the following chapters:
z Chapter 4, “Understanding Portlet Development”
z Chapter 5, “Building Portlets”
z Chapter 6, “Refining and Testing Portlets”
z Chapter 7, “Optimizing Portlet Performance”

z Chapter 8, “Interportlet Communication”
A
ET
B

CHAPTER 4
Understanding Portlet Development
A
This chapter provides conceptual and reference information that you might find useful as you
begin to develop portlets with WebLogic Portal. For a detailed description of the components that
are involved in portlet design, refer to the Portal Development Guide. For instructions on how to
create each type of portlet, refer to “Building Portlets” on page 5-1.
ET
z Resources for Creating Portlets
z Portlet Components
z Portlet Resources in the Database

B
z Portlet Rendering
z JSPs, JSP Tags, and Controls in Portlets
z Backing Files
Resources for Creating Portlets

Although the Portlet Wizard provides an easy way to create portlets, you might find that it is not
your primary means of creating them. You can create a portlet in many ways, such as duplicating
existing portlets or generating a portlet based on an existing JSP or struts module. Many resources
can provide the raw material for a portlet, including the following:
z Portlets in Library Modules - Portlets provided with WLP, which you can copy into your
project and modify for your use.

U nd e r s t an di n g Por t l e t D e v e l o p m e nt
Caution: Portlets that are part of the GroupSpace sample application cannot be used in a
non-GroupSpace-enabled application.
z Third-party portlets - Special-purpose portlets provided as separate products by partner

companies.
z Existing JSPs, Struts modules, and Page Flows – Existing resources that you can drag
onto a portal page to automatically generate a portlet.
You can find detailed instructions on how to use these resources as the basis for a portlet in
Chapter 5, “Building Portlets.”
Portlet Components
The portal file contains all the components that make up that particular instance of the portal, such
as books, pages, portlets, and Look & Feel components.
This section includes the following topics:
z Portlet Properties
A
ET
z Portlet Look & Feel Components
For details about Look & Feel components, refer to the Portal Development Guide.
z Portlet Title Bar, Mode, and State
z Portlet Preferences
Portlet Properties
B
Portlet properties are named attributes of the portlet that uniquely identify it and define its
characteristics. Some properties—such as title, definition label, portlet URI, and Content URI—
are required; many other optional properties allow you to enable specific functions for that portlet
such as scrolling, presentation properties, pre-processing (such as for authorization) and
multi-threaded rendering. The specific properties that you use for a portlet vary depending on
your expected use for that portlet.
For detailed information on portlet properties and how to set them, refer to “Portlet Properties”
on page 6-1.

Po rt l e t R e s o u rc e s i n t he D at a ba s e
Portlet Title Bar, Mode, and State

When you create a portlet, you can choose whether or not it should have a title bar. Also, all
portlets created with WebLogic Portal support modes and states. Modes affect the portlet’s
content; edit, help, float, and custom modes are available. States affect the rendering of the
portlet; minimize, maximize, float, and delete states are available
You must enable the title bar on a portlet if you want to set modes and states for that portlet.
In certain situations your selection of a mode and state for a portlet might affect your ability to
set up other portlet features, such as interportlet communication. For example, if you are setting
up an event handler that listens to a portlet, you can select to execute the event handler only if the
portlet to which it is listening is in a window that is not minimized, and is in view mode.
For detailed instructions on setting portlet modes and states, refer to “Portlet Appearance and
Features” on page 6-32.
Portlet Preferences A
Portlets are distinct applications that you can reuse in a given portal; they are more reusable than
ET
other web components such as servlets, JSPs, or even Java Page Flows. Once you create a portlet,
you can instantiate it several times.
Along with the ability to create multiple instances of portlets, WebLogic Portal allows you to
specify preferences for portlets. You use preferences to cause each portlet instance to behave
differently yet use the same code and user interface. Portlet preferences provide the primary
means of associating application data with portlets; this feature is key to personalizing portlets
based on their usage.
B
Plan a portlet implementation that allows portlets to be as reusable as possible; planning for reuse
simplifies your development and testing efforts because you can differentiate generic portlets by
setting unique preferences.
For detailed instructions on setting portlet preferences, refer to “Portlet Preferences” on
page 6-16.
Portlet Resources in the Database

During the development phase, the .portlet files for portal web projects are stored as XML in
the portal EAR. As a developer creates new .portlet files, a file polling thread monitors
changes and loads the development database with the .portlet information. When a portlet’s

data is loaded into the database, the portlet XML is parsed and a number of tables are populated
with information about the portlet.
This section contains the following sections:
z Types of Database Tables
z Management of Portlet Data
z How the Database Shows Removed Portlets
Types of Database Tables

Separate database tables store information about portlet resources, including the following:
z Definitions – Portlet definition properties including creation date, content URI, whether
the portlet is forkable or cacheable, whether it has a backing file, and so on.
z
A
Instances (including a subset of tables for WSRP) – Instance properties indicate whether
the portlet is minimized by default, title bar orientation (top, left, right, bottom), the parent
portlet instance if applicable, and so on.WSRP portlet properties include proxy portlet
ET
instance values.
z Categories – Portlet categories provide for the classification of portlets, which is useful
when organizing a large collection of portlets into meaningful groupings. The database
stores values for the category ID and creation/modification dates.
z Category definitions – The database stores values for the category ID and
creation/modification dates, parent category, and so on.
B
z Preferences – Preference properties, such as whether or not the preference can be

multi-valued or whether it is modifiable, are stored in this table.
z Preference values – The database stores the actual value of portlet preferences.
z User properties – The database table maintains values of portlet user properties for WSRP
user profile propagation.
Management of Portlet Data

When a portlet is loaded into the database, the portlet XML is parsed and a number of tables are
populated with information about the portlet, including PF_PORTLET_DEFINITION,
PF_MARKUP_DEFINITION, PF_PORTLET_INSTANCE, PF_PORTLET_PREFERENCE,
L10N_RESOURCE, and L10N_INTERSECTION.

Po rt l e t R e s o u rc e s i n t he D at a ba s e
PF_PORTLET_DEFINITION is the master record for the portlet and contains rows for properties
that are defined for the portlet, such as the definition label, the forkable setting, edit URI, help
URI, and so on. The definition label and web application name are the unique identifying records
for the portlet. Portlet definitions refer to the rest of the actual XML for the portlet that is stored
in PF_MARKUP_DEF.
PF_MARKUP_DEF contains stored tokenized XML for the .portlet file. This means that the
.portlet XML is parsed into the database and properties are replaced with tokens. For example,
the following code fragment shows a tokenized portlet:
<netuix:portlet $(definitionLabel) $(title) $(renderCacheable)
$(cacheExpires)>
These tokens are replaced by values from the master definition table in
PF_PORTLET_DEFINITION, or by a customized instance of the portlet stored in
PF_PORTLET_INSTANCE.
properties:
z
A
The following four types of portlet instances are recorded in the database for storing portlet
Primary – Properties defined in development and stored in the .portlet file.

ET
z Library – Properties defined in the Portal Library, which may be changed using the
WebLogic Administration Portal.
z Admin – A customized instance of the portlet in a desktop. This allows you to customize a
portlet in a particular way for a desktop without affecting other instances of the portlet in
other desktops.
B
z User – User-customized instances of the portlet defined in the Visitor Tools.

PF_PORTET_INSTANCE contains properties for the portlet for attributes such as
DEFAULT_MINIMIZED, TITLE_BAR_ORIENTATION, and PORTLET_LABEL.
If a portlet has portlet preferences defined, those are stored in the PF_PORTLET_PREFERENCE
table.
Finally, portlet titles can be internationalized. Those names are stored in the L10N_ RESOURCE
table which is linked using L10N_INTERSECTION and PF_PORTLET_DEFINITION.
How the Database Shows Removed Portlets

If a portlet is removed from a deployed portal project, and it has already been defined in the
production database, the portlet is marked as IS_PORTLET_FILE_DELETED in the

PF_PORTLET_DEFINITION table. The portlet displays as grayed out in the Administration

Console, and user requests for the portlet (if it is still contained in a desktop instance) return a
message indicating that the portlet is unavailable.
For detailed information about the content of WebLogic Portal database tables, refer to the BEA
WebLogic Portal Database Administration Guide.
Portlet Rendering
Portlet rendering consists of two processes:
z Pre-rendering – The background work to obtain necessary data or to perform

pre-processing
z Rendering – The actual drawing of the portlet onto the portal page
following portlet-specific rendering topics:
z Render and Pre-Render Forking

A
General rendering topics are covered in the Portal Development Guide. This section contains the
ET
z Asynchronous Portlet Content Rendering
Render and Pre-Render Forking

By default, pre-rendering and rendering for each portlet on a page is performed in sequence, and
the portal page is not displayed until processing is complete for every portlet. This sequence can
cause a noticeable delay in displaying the web page and might cause a user to think there is a
B
problem with the web site. To prevent this situation, you can set up your portlets so that they
perform pre-rendering and rendering tasks in parallel using multi-threaded forked processing.
Forking portlets at the rendering stage is supported for all portlet types. Pre-render forking is
supported for the following portlet types:
z JSP
z Page flow
z Java (JSR168)
z WSRP (consumer portlets only)

For detailed instructions on implementing forked portlets, refer to “Parallel Portlet Rendering”
on page 7-3.

J SP s, JS P Tag s, an d Co nt ro ls in Por t let s
Asynchronous Portlet Content Rendering

Asynchronous portlet rendering allows the content of a portlet to be rendered independently of
the surrounding portal page. When using asynchronous portlet rendering, a portlet is rendered in
two phases. The first phase is the normal portal page request during which the portlet's
non-content areas, such as the title bar, is rendered; a second request causes the portlet's content
to render within the embedded document.
For detailed instructions on implementing asynchronous content rendering, refer to
“Asynchronous Portlet Content Rendering” on page 7-5.
Portlets as Popups (Detached Portlets)

WebLogic Portal supports the use of detached portlets. Detached portlets provide popup-style
behavior. You can see examples of detached portlets within WebLogic Portal in the GroupSpace
A
Message Center and in the Administration Console wizards.
For detailed instructions on using detached portlets, refer to “Detached Portlets” on page 5-27.
JSPs, JSP Tags, and Controls in Portlets

ET
WebLogic Portal provides JSP tags that you can use within JSPs. Portlets can use JSPs as their
content nodes, enabling reuse and facilitating personalization and other programmatic
functionality. You can create JSPs with Workshop for WebLogic to provide a structure for other
elements to be added to a portlet.
Workshop for WebLogic also provides Java controls that make it easy for you to encapsulate
B
business logic and to access enterprise resources such as databases, legacy applications, and web
services. There are three different types of Java controls: built-in Java controls, portal controls,
and custom Java controls.
For detailed information about using JSPs, JSP tags, and controls within portlets, see “JSPs, JSP
Tags, and Controls in Portlets” on page 6-42.
Backing Files
The most common means of managing portlet behavior within the control life cycle is to use a
portlet backing file. A portlet backing file can contain methods that correspond to Portal control
life cycle stages, such as init() and preRender(). You can use a portlet’s backing context, an
abstraction of the portlet control itself, to manage the portlet’s characteristics. For example, in the
init() life cycle method, a request parameter might be evaluated, and depending on the

parameter’s value, the portlet backing context can be used to specify whether the portlet is visible
or hidden.
Backing files allow you to programmatically add functionality to a portlet by implementing (or
extending) a Java class, which enables preprocessing (for example, authentication) prior to
rendering the portal controls. Backing files work in conjunction with JSPs. The JSPs allow you
to code the presentation logic, while the backing files allow you to code simple business logic.
Backing files are always run before the JSPs. Backing files can be attached to portals either by
using Workshop for WebLogic or coding them directly into a .portlet file.
For detailed instructions on implementing backing files, refer to “Backing Files” on page 7-10.
A
ET
B

CHAPTER 5
Building Portlets
A
This chapter describes the most common ways to create portlets, including the Portlet Wizard and
the use of out-of-the-box portlets. This chapter also contains instructions for building each type
of portlet that is supported by WebLogic Portal.
Before you begin, be sure you are familiar with the concepts associated with creating portlets, as
ET
described in Chapter 4, “Understanding Portlet Development.”
z Portlets in Library Modules
z Third-Party Portlets
B
z Portlet Wizard Reference
z How to Build Each Type of Portlet
z Detached Portlets
z Special Considerations When Building Portlets
Portlets in Library Modules

You can copy portlets or other resources from a library module into your portal application and
modify them as needed. To see a list of available portlets, you can use the Merged Projects View
of the workbench; resources contained in library modules are shown in italic print. You can
expand the tree to see the resources that are strored in the various modules. For a reference list of

Buil din g Po rt let s
all the library modules and their locations on your file system, you can select Window >
Preferences > WebLogic > Library Modules.
After you locate a portlet that you want to use, you can right-click the portlet in the Merged
Projects View and select the Copy to Project option. Figure 5-1 shows an example of a library
module portlet in the Merged Projects view with the Copy to Project option selected.
Caution: Portlets that are part of the GroupSpace sample application cannot be used in a
non-GroupSpace-enabled application.
Figure 5-1 Portlet Being Copied to a Project from Merged Projects View
A
ET
For more information about library modules, refer to the Portal Development Guide.
B
Third-Party Portlets
WebLogic Portal partner companies create special-purpose portlets that you can easily
incorporate into your portal; these companies include Autonomy, Documentum, and
MobileAware.
The following sections provide more information about third-party portlets:
z Autonomy Portlets
z Documentum Portlets
z MobileAware Portlets

T h i r d- P ar ty Por t l e t s
Autonomy Portlets
WebLogic Portal includes an embedded license of Autonomy-based search capabilities. You can
use these capabilities to integrate enterprise-class search into your portal; common use cases
include integration with content management systems, relational databases, and external web
sites. You can expose these sources of information for searches using portlets that some with
WebLogic Portal, and developers can use Autonomy APIs as they author new portlets and
business logic for integrating search into your portal as well.
In WebLogic Portal Version 9.2, the BEA proprietary search APIs are deprecated; we
recommend that you use Automony APIs to implement search capabilities.
To review the documentation for Autonomy, refer to the Third Party section of the e-docs web
site.
Documentum Portlets
A
EMC Documentum has partnered with BEA to offer EMC Documentum Content Services for
BEA Weblogic Portal. This product provides a packaged set of Documentum functionality
exposed through the BEA WebLogic Portal infrastructure, allowing users to access and interact
ET
with all types of enterprise content including web pages, documents, and rich media such as audio
and video.
From a portlet development perspective, a key feature of this product is the inclusion of
Documentum portlets—tested and certified application components that expose standardized,
enhanced content management user functions through the portal interface.
Documentum portlets expose four key applications:
B
z Content management portlets allow users to manage any type of content.
z Web Publisher portlets permit casual users to publish content to web sites and portals.
z eRoom portlets provide dashboard views into EMC Documentum eRooms and allow
multiple project management.
z The Enterprise Content Integration (ECI) Services portlet enables continuous access to
content in other repositories, databases, and Web sites.
For more information on Documentum portlets for WebLogic Portal, you can visit the
Documentum web site.

MobileAware Portlets
BEA WebLogic Mobility Server provides a standards-based, non-proprietary environment that
extends BEA WebLogic deployments to offer multichannel mobile services in significantly
reduced timeframes. Enterprises can broaden the effectiveness of business-critical systems for
employees and customers, and mobile carriers can rapidly deploy new, data-centric services,
without the need for re-training and re-tooling.
For more information about BEA WebLogic Mobility Server and how to use it with WebLogic
Portal, see the product documentation on the e-docs web site.
Portlet Wizard Reference

An important tool that you can use to create portlets from scratch is the WebLogic Portal Portlet
Wizard. The following sections describe the Portlet Wizard in detail:
z
Order of Creation - Resource or Portlet First
Starting the Portlet Wizard

A
ET
z Select Portlet Type Dialog
z Portlet Details Dialogs

In general, you choose the portlet type on the first dialog of the wizard; when generating a portlet
based on an existing resource, the Portlet Wizard automatically detects the portlet type whenever
possible.
B
Order of Creation - Resource or Portlet First

This section provides an overview of the two methods you can use to begin creating a portlet—
creating the portlet resource information/file first or creating the portlet itself first.
Creating the Resource First

You might already have a JSP file, for example, that you want to use as the basis for a portlet. In
this situation, you can follow these steps to create a portlet based on that resource:
1. Create or open a portal's .portal file in Workshop for WebLogic.
2. Drag the resource, such as a JSP file, into one of the portal's placeholder areas in the design
view in the editor.

Po rt le t W iza rd Ref er en ce
Workshop for WebLogic prompts you with a dialog similar to the example in Figure 5-2.
Figure 5-2 Portlet Wizard Prompt Following Drag and Drop of a Resource
If you click Yes, the Portlet Wizard uses information from the resource file to begin the
process of creating a portlet, and displays the Portlet Details dialog. Figure 5-3 shows an
example:
Figure 5-3 Example Portlet Wizard Details Dialog Following Drag and Drop of a Resource
A
ET
B
In addition to JSP files, you can drag other resources onto the portal, such as content selectors.

Create the Portlet First

If you do not have an existing source file to start with, you can create the portlet using the New
Portlet dialog and the Portlet Wizard. To do so, right-click a folder in your portal web project and
select New > Portlet. Figure 5-4 shows an example of the New Portlet dialog.
Figure 5-4 Portlet Wizard New File Dialog
A
ET
B
After you confirm or change the parent folder, name the portlet, and click Finish, the Portlet
Wizard begins and displays the Select Portlet Type dialog. Figure 5-5 shows an example dialog.

Figure 5-5 Portlet Wizard - Select Portlet Type Dialog
A
ET
Detailed instructions for creating each type of portlet are contained in “How to Build Each Type
of Portlet” on page 5-10.
Starting the Portlet Wizard

Workshop for WebLogic invokes the Portlet Wizard any time you perform one of these
B
operations:
z Select File > New > Portlet from Workshop for WebLogic's top-level menu, or right-click
a folder in your web application, and select New > Portlet. After you name the portlet and
click Create, the Portlet Wizard starts.
z Drag and drop a resource such as a JSP from the Package Explorer view onto a placeholder
area of an open portal (in other words, a Portal_Name.portal file is open in the editor
view of the workbench.) Workshop for WebLogic prompts you with a dialog similar to the
example in Figure 5-6.

Figure 5-6 Portlet Wizard Prompt Following Drag and Drop of a Resource
If you click Yes, the Portlet Wizard uses information from the resource file to begin the
process of creating a portlet.
z Right-click an existing resource such as a JSP file, a page flow, a portal placeholder, or a
portal content selector; then select Generate Portlet from the context menu. The Portlet
Wizard displays the Portlet Details dialog. Figure 5-7 shows an example of a dialog after
right-clicking a JSP file.
A
Figure 5-7 Portlet Wizard - Portlet Details Example for JSP Resource
ET
B

New Portlet Dialog

When you use File > New > Portlet to create a new portlet, a New Portlet dialog displays before
the Portlet Wizard begins. Figure 5-4 shows an example of the New Portlet dialog.
The parent folder defaults to the location from which you selected to add the portlet.
This dialog requires that you select a project and directory for the new portlet, and provide a
portlet file name. (The file name appears in the Package Explorer view after you create the
portlet.) The Finish button is initially disabled; the button enables when you select a valid
project/directory and portlet name. If you select an invalid portal project in the folder tree on this
dialog, an error message appears in the status area near the top of the dialog explaining that the
project is not a valid portal project. You cannot continue until you have selected a valid project
(if one is available).
Note: Beginning with WebLogic Portal Verson 9.2, the option to convert a non-portal project
A
to a portal project is not offered here. For information on how to integrate portal library
modules into an already existing project, see the Portal Development Guide.
Select Portlet Type Dialog

ET
When the Portlet Wizard starts, it determines the valid portlet types to offer on the Select Portlet
Type dialog, based on the type of project that you are working in.
For example, if you are working within a Portal Web Project that has only the WSRP-Producer
feature (and its required accompanying features) installed, it does not have the full set of portal
libraries. In this case, only the JPF, JSF, Browser, and Struts portlet types are valid selections; the
other portlet types are not included in the Select Portlet Type dialog.
B
If no valid portlet types exist based on the project type, an informational message displays.
Figure 5-8 shows an example of the Select Portlet Type dialog.

Figure 5-8 Portlet Wizard - Select Portlet Type Dialog
A
ET
Portlet Details Dialogs
The Portlet Details dialogs that display after you select a portlet type vary according to the type
of portlet you are creating. The portlet-building tasks that are described in “How to Build Each
Type of Portlet” on page 5-10 contain detailed information about each data entry field of the
portlet details dialogs.
B
How to Build Each Type of Portlet

The following sections describe how to create each type of portlet supported by WebLogic Portal:
z JSP and HTML Portlets
z Java Portlets
z Java Page Flow Portlets
z JSF Portlets
z Browser Portlets

How to Buil d E ac h T y pe of Po rt let
z Struts Portlets
z Remote Portlets
JSP and HTML Portlets

JSP portlets are very similar to simple JSP files. In most cases you can reuse existing JSP files to
build portlets from them. JSP portlets are recommended when the portlet is simple and doesn’t
require the implementation of complex business logic. Also, JSP portlets are ideally suited for
single page portlets.
There are several ways to invoke the Portlet Wizard, as explained in the section “Starting the
Portlet Wizard” on page 5-7. This description assumes that you create a portlet based on an
existing JSP file.
To create a JSP portlet, follow these steps:
A
1. Right-click a JSP file and select Generate Portlet from the menu.
The Portlet Wizard displays the Portlet Details dialog; Figure 5-9 shows an example.
ET
Figure 5-9 Portlet Wizard - JSP Portlet Details Dialog
B

2. Specify the values you want for this portlet, following the guidelines shown in Table 5-1.
Table 5-1 Portlet Wizard - JSP Portlet Data Entry Fields

Field Description
Title The value for the Title might already be filled in.You can change the value
if you wish.
Content URI The value for the Content URI (location of the JSP) is probably already
filled in. You can change this value if you wish.
Error Page URI To designate a default error page to appear in case of an error, check the
box and indicate the path to the desired URI.
Has Titlebar If you want your portlet to have a title bar, check this box. The displayed
title matches the value in the Title field. In order for a portlet to have
State A
changeable states or modes, the portlet must have a title bar.
Select the desired checkboxes to allow the user to minimize, maximize,

float, or delete the portlet. For a more detailed description of portlet states,
refer to “Portlet States” on page 6-38.
ET
Available Modes You can enable access to Help from the portlet or you can allow the user to
edit the portlet.
To enable an option, select the desired checkbox and provide the path to the
JSP page that will provide the appropriate function. For a more detailed
description of portlet modes, refer to “Portlet Modes” on page 6-35.
B
3. Click Finish.
The Workshop for WebLogic window updates, adding the Portlet_Name.portlet file to the
display tree; by default, Workshop for WebLogic places the portlet file in the same
directory as the content file.
Java Portlets
Java Portlets are based on the JSR 168 specification that establishes rules for portability between
portlets and portals. Java Portlets are intended for software companies and other enterprises that
are concerned with portability across multiple portlet containers. For information about the
emerging JSR 168 work, refer to the article “Developing JSR 168 Portlets with WebLogic
Portal” on the BEA dev2dev site <link TBD>.

WebLogic Portal provides capabilities for Java portlets beyond those listed in the JSR168 spec.
For example, you can set threading options, or use a backing file, and so on. To implement these
additional features, WebLogic Portal uses a combination of the typical .portlet file—which
you create in the same way that you create other portlet types—as well as the standard
portlet.xml file.
The mapping between the portlet.xml file and the .portlet file is that the portlet-name attribute in
the portlet.xml file matches the definitionLabel property in the .portlet file.
Building a Java Portlet

To create a Java portlet, follow these steps:
1. Right-click the folder where you want to store the portlet and select New > Portlet.
The New Portlet dialog displays.
2. Enter a name for the portlet and click Create.

A
The Portlet Wizard displays the Select Portlet Type dialog.
3. Select the Java Portlet radio button and click Next.

ET
The Java Portlet Details dialog displays. Figure 5-10 shows an example.
Figure 5-10 Portlet Wizard - Java Portlet Details Dialog

B

4. Identify whether you want to create a new portlet or update an existing portlet (as an entry in
the portlet.xml file) by selecting the appropriate radio button.
If you are creating a new portlet, WebLogic Portal uses the information that you enter in
the wizard to perform these two tasks:
– Create a new .portlet file
– Either create a new portlet.xml file (if this is the first Java portlet that you are
creating in the project), or add an entry in the portlet.xml file, which is located in
the WEB-INF directory.
If you choose to refer to an existing portlet in the wizard, the wizard displays a selection
for every entry in the portlet.xml file, allowing you to create a new .portlet file and
associate it with an existing entry in the portlet.xml file.
5. Specify the values you want for this portlet, following the guidelines shown in Table 5-2. All
fields are required.
Table 5-2 Portlet Wizard - Java Portlet Data Entry Fields

Field Description
A
ET
New Portlet – The value for the Title maps to the <title> element in the file portlet.xml.
Title
New Portlet – This value is similar to a definition label for any portlet; however, the value also
Definition Label maps to the <portlet-name> element in the portlet.xml deployment
descriptor.
B
New Portlet – Enter a valid class name or click Browse to navigate to the location of a Java class.
Class Name This value maps to the <portlet-class> element.
Existing Portlet – The dropdown menu is populated from the portlet.xml file and contains the
Select From List values from the <portlet-name> elements.
When you select an existing portlet, the Title and Class Name display in read-only
fields.
Note: If you import an existing Java portlet into Workshop for WebLogic, you
do not need to add an entry in the web.xml file for the WebLogic Portal
implementation of the JSR-168 portlet taglib; this taglib is declared
implicitly. Be sure to use http://java.sun.com/portlet as the
taglib URI in your JSPs.
6. Click Finish.

Based on these values that you entered, the Wizard creates a .portlet file, and adds an
entry to /WEB-INF/portlet.xml, if it already exists, or creates the file if needed.
Workshop for WebLogic displays the newly created portlet and its current properties.
Figure 5-11 shows an example of a Java portlet’s appearance and properties.
Figure 5-11 Java Portlet Appearance and Properties
A
ET
After you create the portlet, you can modify its properties in the Properties view, or double-click
the portlet in the editor to view and edit the generated Java class.
Note: If you delete a .portlet file, the corresponding entry remains in the portlet.xml file.
You might want to clean up the portlet.xml file periodically; these extra entires do not
cause problems when running the portal but do result in error messages in the log file.
B
Java Portlet Deployment Descriptor

The separate portlet.xml deployment descriptor file for Java portlets is located in the WEB-INF
directory. In addition, the weblogic-portlet.xml file is an optional portal-specific file that you
can use to inject some additional features.
Listing 5-1 shows an example of how entries might look in the portlet.xml file:
Listing 5-1 Example of a portlet.xml file for a Simple Hello World Java Portlet
<?xml version="1.0" encoding="UTF-8"?>

<portlet-app version="1.0"
xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet">
<portlet>
<description>Description goes here</description>
<portlet-name>helloWorld</portlet-name>
<portlet-class>aJavaPortlet.HelloWorld</portlet-class>
<portlet-info><title>Hello World!</title></portlet-info>
</portlet>
</portlet-app>
Packaging Java Portlets for Use on Other Systems
A
WebLogic Portal produces Java portlets that conform to the JSR 168 specification and can be
used universally across operating systems. To package a Java portlet that you created using
WebLogic Portal, use your desired packaging/archiving tool to create a standard WAR file that
contains the portlet.xml file, portlet .class file, and any other files the portlet needs to
ET
function. Keep in mind that these required files might include Java classes from non-WebLogic
Portal JARs, any non-BEA EJBs from the application, JSPs or HTML files to handle rendering,
and so on.
Customizing Java Portlets Using weblogic-portlet.xml

WebLogic Portal allows you to add more functionality to java portlets than you can obtain using
B
the standard JSR 168 specification. You can use the optional weblogic-portlet.xml fileto
inject some additional features. the following sections provide some examples.
Floatable Java Portlets

If you want to create a floatable Java portlet, you can do so by declaring a custom state in
weblogic-portlet.xml as shown in the following example code:
<portlet>
<portlet-name>fooPortlet</portlet-name>
<supports>
<mime-type>text/html</mime-type>
<window-state>
<name>float</name>

</window-state>
</supports>
</portlet>
Adding an Icon to a Java Portlet

To add an icon to a Java portlet, you need to edit the weblogic-portlet.xml file, as described
in this section.
1. Place the icon in the images directory of the skin that the portal is using. For example, if the
skin name is avitek, icons must be placed in:
myPortal/skins/avitek/images
2. In the Application panel, locate and double-click the weblogic-portlet.xml file to open it.
This file is located in the portal's WEB-INF folder, for example:
myPortal/WEB-INF/weblogic-portlet.xml
A
3. Add the following lines to the weblogic-portlet.xml file:
<portlet>
ET
<portlet-name>myPortlet</portlet-name>
<supports>
<titlebar-presentation>
<icon-url>myIcon.gif</icon-url>
</titlebar-presentation>
</supports>
</portlet>
B
4. Make these substitutions:

– Change myPortlet to the name of the portlet that is specified in WEB-INF/portlet.xml
– Be sure the mime-type also matches the mime-type found in WEB-INF/portlet.xml
– Change myIcon.gif to the name of the icon you wish to add
Java Page Flow Portlets

You can use the Portlet Wizard to built a portlet that uses Java Page Flows to retrieve its content.
To create a page flow portlet, follow these steps:
1. Right-click the folder where you want to store the Page Flow portlet. (The folder must be
within the WebContent directory.)

2. Select New > Portlet.

The New Portlet dialog displays.
3. Enter a name for the portlet and click Create.

4. Select the Java Page Flow Portlet radio button and click Next.
Figure 5-12 Portlet Wizard - JPF Portlet Details Dialog
A
ET
B

Table 5-3 Portlet Wizard - JPF Portlet Data Entry Fields

Field Description
Title The title for this portlet, which displays in the title bar if you select to
include one.
Content Path The Page Flow Request URI. You can type a value here, or click the
Browse button to open a class picker and select the appropriate class.
If you use the class picker to choose a Page Flow class, this fully-qualified
class name is converted to a URI path of a JPF. The JPF does not reside in
the project, but is referred to by the .portlet file when the portlet is
created.
(In the current release, you can choose only types for classes within the
project. In a future release, when the Eclipse JDT supports accessing
A
class-level annotations within the IClassFileReader API, WebLogic Portal
will be able to definitively determine if a class is a Page Flow.)
If you enter or navigate to a .jpf that has no corresponding class in the
project or library modules, the Portlet Wizard creates the .java file for the
ET
Page Flow. If multiple project source directories exist, then the wizard
prompts you to store the new .java file in the source directory of your
choice. The .java template refers to a .jpf that is also created as part of
this operation. The .jpf is created in the web content directory using the
same directory structure as the package name of the new Page Flow class.
Error Page Path To designate a default error page to appear in case of an error, check the
B
State Select the desired checkboxes to allow the user to minimize, maximize,
edit the portlet.

6. Click Create.
The Workshop for WebLogic window updates, adding the Portlet_Name.portlet file to
the display tree; by default, Workshop for WebLogic places the portlet file in the same
In order to fully understand the process of creating a Page Flow portlet, you should be familiar
with the concept of Page Flows. For more information on using page flows with WebLogic
Portal, refer to the Portal Development Guide.
If you want to create a page flow portlet that calls a web service, refer to “Web Service Portlets”
on page 5-27.
JSF Portlets
To create a JSF portlet, follow these steps:
> Portlet from the menu. A

1. Right-click in the Package Explorer view, within the web content directory, and select New
The New Portlet dialog displays. Figure 5-15 shows an example of the New Portlet dialog.
ET
B

Figure 5-13 Portlet Wizard - New Portlet Dialog
A
ET
B
2. Edit the parent folder field if needed to indicate the project and directory for the new portlet.
The Finish button is initially disabled; the button enables when you select a valid parent
folder and portlet name. If you select an invalid portal project in the folder tree on this
dialog, an error message appears in the status area near the top of the dialog explaining that
the project is not a valid portal project.
3. Type a file name for the new portlet.
4. Click Finish to continue.

5. Click Java Server Faces (JSF) Portlet and then click Next.

Figure 5-14 Portlet Wizard - JSF Portlet Details Dialog
A
ET
Table 5-4 Portlet Wizard - JSF Portlet Data Entry Fields

B
Field Description
Title The value for the portlet title, which displays in the title bar if enabled.
Content Path The value for the Content URI.
Error Page Path To designate a default error page to appear in case of an error, check the

Table 5-4 Portlet Wizard - JSF Portlet Data Entry Fields (Continued)
Field Description
edit the portlet.
file that will provide the appropriate function. For a more detailed
7. Click Create.
display tree.
A
Note: If you want to have more than one JSF portlet on a portal page, you must use the
namingContainer JSP tag immediately after a JSF view tag, in order to provide
ET
component naming in the generated component tree. For details about this tag, refer to
the Javadoc.
Browser Portlets
Browser portlets, also called Content URI portlets, are basically HTML portlets that use URLs to
retrieve their content. Unlike other portlet types that are limited to displaying data contained
B
within the portal project, browser portlets can display URL content that is outside from the portal
project.
There are several ways to invoke the Portlet Wizard, as explained in the section “Starting the
Portlet Wizard” on page 5-7. This description assumes that you right-click in the Package
Explorer view tree within a portal project and select New > Portlet from the menu.
To create a browser portlet, follow these steps:
1. Right-click in the Navigation tree within a portal project and select New > Portlet from the
menu.
The New Portlet dialog displays. Figure 5-15 shows an example of the New Portlet dialog.

Figure 5-15 Portlet Wizard - New Portlet Dialog
A
ET
B
2. Edit the parent folder field if needed to indicate the project and directory for the new portlet.
The Finish button is initially disabled; the button enables when you select a valid parent
folder and portlet name. If you select an invalid portal project in the folder tree on this
dialog, an error message appears in the status area near the top of the dialog explaining that
the project is not a valid portal project.
3. Type a file name for the new portlet.
4. Click Finish to continue.

5. Click Browser (URL) Portlet and then click Next.


Figure 5-16 Portlet Wizard - Browser Portlet Details Dialog
A
ET
Table 5-5 Portlet Wizard - Browser Portlet Data Entry Fields

Field Description
Title The title for the portlet. This value appears in the title bar of the portlet in
B
the editor view of the Workshop for WebLogic workbench.
Content URL The value for the Content URL (external URL) that the portlet should use
to retrieve its information.
A validator checks the format of the URL that you enter, and a message
notifies you if the URL is not properly formatted. You can either change
the URL or ignore the warning and continue with the URL as is.

Table 5-5 Portlet Wizard - Browser Portlet Data Entry Fields (Continued)
Field Description
edit the portlet.
7. Click Finish.
A
display tree; by default, Workshop for WebLogic places the portlet file in the same
Note: The internal implementation of Browser portlets depends on asynchronous portlet
ET
content rendering; because of this, the portlet attribute Async Content displayed in the
Porperties view is set to none and is read-only. For more information about asynchronous
content rendering, refer to “Asynchronous Portlet Content Rendering” on page 7-5.
Struts Portlets
You can use the Portlet Wizard to generate a portlet based on a Struts module.
B
This section is not available for the Beta release.
Remote Portlets
Because remote portlet development is a fundamental task in a federated portlet environment, the
task of creating remote portlets is described in detail within the BEA WebLogic Portal Federated
Portals Guide.
The following types of portlets can be exposed with WSRP inside a WebLogic portal:
z Page Flow portlets
z JavaServer Pages (JSP) portlets

De tached Portlets
z Struts portlets
z Java portlets (JSR168; supported only for complex producers)
z JavaServer Faces (JSF) portlets
Web Service Portlets

A web service portlet is a special type of Page Flow portlet, allowing you to call a web service.
You create web service portlets using the features of Workshop for WebLogic and WebLogic
Portal.
This section is not available for the beta release.
Detached Portlets
A
WebLogic Portal supports the use of detached portlets, which provide popup-style behavior.
Technically, a detached portlet is defined as anything outside of the calling portlet/context. Any
portlet type supported by WebLogic Portal can be implemented as a detached portlet.
ET
Considerations for Using Detached Portlets
Keep the following considerations in mind as you implement detached portlets:
z Detached portlets are never referenced from within a portal.
z Detached portlets can be streamed but generally cannot be entitled or customized; the
B
library instance can be entitled, but portlet instances that are de-coupled from the portlet
library cannot. For more information about library portlet instances and de-coupling, refer
to the Production Operations Guide.
z Detached portlet are not visible or accessible from the WebLogic Portal Administration
Console portlet library.
z In a streamed portal, the primary instance of the portal is used; in cases where the primary
instance cannot be determined, a static version of the portlet will be used (the portlet will
be served in file mode). In these cases, some features related to a streamed portal (such as .
community context) will not be available, and applications might be required to implement
workarounds.
z Although technically a detached portlet can be implemented to use asynchronous

rendering, this is not a best practice and is not recommended.

z No presentation mechanism is provided as part of the detached portlet feature; the

application must define how to actually present the portlet.
z When developing detached portlets, you can place them anywhere in the hierarchy of your
portal; the portlal references the absolute path to the portlet. A good example of a detached
portlet is the GroupSpace member list portlet.
Building Detached Portlets

You use the standalonePortletUrl class or associated JSP tag to create URLs to detached
portlets. Use standalonePortletUrl to create links to submit requests to detached portlets,
such as floating portlets, that are hosted by an external portal.
To create a detached portlet URL from a JSP page, you can use the render:standalonePortletUrl
JSP tag; the following example shows the syntax of the tag:
<render:standalonePortletUrl
A
portletUri="/absolute_path/detached_portlet_name.portlet" …/>
To create a detached portlet URL from Java code, use the following example as a guide:
StandalonePortletURL detachedURL =
ET
StandalonePortletURL.createStandalonePortletURL(request, response);
detachedURL.setPortletUri(“/path/to/detached.portlet”);
Special Considerations When Building Portlets

TBD
B

CHAPTER 6
Refining and Testing Portlets
A
This chapter contains instructions for adding to, customizing, and testing your portlets after you
have created them. This chapter also contains some reference information to keep in mind as you
are developing portlets.
ET
z Portlet Properties
z Portlet Preferences
z Portlet Appearance and Features
z JSPs, JSP Tags, and Controls in Portlets

B
z Portlet Events
z Error Handling
z Portlet State Persistence
z Adding a Portlet to a Portal
z Removing and Deleting Portlets
Portlet Properties
Portlet properties are named attributes of the portlet that uniquely identify it and define its
characteristics. Some properties—such as title, definition label, portlet URI, and content URI—
are required; many optional properties allow you to enable specific functions for the portlet such

Refini ng and Testing Portlets
as scrolling, presentation properties, pre-processing (such as for authorization) and

multi-threaded rendering. The specific properties that you use for a portlet vary depending on
your expected use for that portlet.
During the development phase of the portal life cycle, you generally edit portlet properties using
the Workshop for WebLogic interface; this section describes properties that you can edit using
Workshop for WebLogic.
During staging and production phases, you typically use the WebLogic Portal Administration
Console to edit portlet properties; only a subset of properties are editable at that point. For
instructions on editing portlet properties from the WebLogic Portal Administration Console, refer
to “Modify Portlet Properties in a Staging Environment” on page 9-5.
For a detailed description of all portlet properties, refer to “Portlet Properties in the Portal
Properties View” on page 6-4 and “Portlet Properties in the Portlet Properties View” on page 6-6.
This section contains the following topics:
z
Editing Portlet Properties
Tips for Using the Properties View in the Workbench

A
ET
z Portlet Properties in the Portal Properties View
z Portlet Properties in the Portlet Properties View
Editing Portlet Properties

To edit portlet properties, follow these steps:
B
1. Navigate to the location of the portlet whose properties you want to edit, and double-click the
.portlet file to open it in the workbench editor.
2. Click the outer border of the portlet file to display the properties for the portlet in the
Properties view.
The displayed properties vary according to the active area that you select. If you click the
outer border, properties for the entire portlet appear; if you click the inner border,
properties for the content of the portlet appear, and so on.
3. Navigate to the Properties view to view the current values for the portlet properties.
Figure 6-1 shows a segment of a JSP portlet’s Properties view:

Portl et Properti es
Figure 6-1 Editing Portlet Properties - JSP Portlet Properties View Example
4. Double-click the field that you want to change.

If you hover the mouse over a property field, a description of that field displays in a popup
window.
Values for some portlet properties are not editable after you create the portlet.
In some cases, from the property field you can view associated information pertaining to
that portlet property; for example, the Java portlet Class Name property contains a
A
read-only value with an Open button to view the associated Java file. For more
information about options available in the Properties view, refer to “Tips for Using the
Properties View in the Workbench” on page 6-3.
ET
Tips for Using the Properties View in the Workbench
The behavior of the Properties view varies depending on the type of field you are editing. The
following tips might help you as you manipulate the content of the data fields in the Properties
view.
z If a file is associated with a portlet property, the Properties view includes an Open button
B
in addition to a Browse button; you can click Open to display the appropriate Eclipse
editor/view for the file type.
z If you want to edit the XML source for a portlet, you can right-click the .portlet file in
the Package Explorer view and choose Edit with > XML Editor to open the file using the
basic XML editor that Eclipse provides.
z The book, page, and portlet actions in the palette display properties in the Properties view
when you select them in the palette. The cell editor for the content file property is read
only, and includes an Open button; clicking Open displays the Eclipse editor/view for the
applicable file type.
z For Page Flow portlets, a property editor is available for Page Flow content paths when
displaying a Page Flow portlet in the editor. The property editor is a dialog cell editor that
allows you to type in the URI of the Page Flow directly, or you can click the elipses

button to launch the Page Flow class picker dialog. If you open the dialog, the Page
Flow class name is converted to a URI when you leave the dialog. WebLogic Portal stores
the URI in the .portlet file when you save the portlet. The property editor validates the
Page Flow URI specified and warns you if you choose a URI that has no corresponding
Page Flow class. You can choose to proceed anyway and store an invalid URI; you should
create a valid class later so that the portlet works correctly.
z For Page Flow portlets, while in the portlet editor you can double-click the portlet content
view to launch the corresponding Java element specified in the portlet content path. This
consists of the Page Flow source if the source is available in the project or attached to the
JAR containing the class. If the source cannot be located, then the disassembled class
browser is displayed showing the contents of the class.
Portlet Properties in the Portal Properties View

The properties described in this section are contained within the .portal file and are editable
A
using the Workshop for WebLogic workbench. The values you enter here override the
corresponding value in the .portal file, if a value exists there.
To display the portlet properties that display in the Properties view for a portal, follow these steps:
ET
Note: These steps assume that you have an existing portal that contains portlets.
1. Double-click the .portal file of the portal for which you want to view portlet instance
properties.
A WYSIWYG view of the portal appears in the editor.
2. Click a portlet to highlight it.

B
An orange border appears around the outside edge of the portlet.

The Properties view displays the properties of the portlet instance; Figure 6-1 shows an example.

Figure 6-1 Portlet Instance Properties in the Portal Properties View
Table 6-1 describes these properties and their values.
Table 6-1 Portlet Instance Properties in the Properties View

Property
Default Minimized
Value A
Optional. Select true for the portlet to be minimized when it is rendered. The
ET
default value is false. Change the value for this property only if you want to
override the default value provided by the .portlet file.
Instance Label Required. A single portlet, represented by a .portlet file, can be used multiple
times in a portal. Each use of that portlet is a portlet instance, and each portlet
instance must have a unique ID, or Instance Label. A default value is entered
automatically, but you can change the value. Instance Labels are necessary for
inter-portlet communication between Java Page Flow portlets. Also, portlets must
B
have Instance labels for entitlements and delegated administration.
Orientation Optional. Hint to the skeleton to position the portlet title bar on the top, bottom,
left, or right side of the portlet. You must build your own skeleton to support this
property. The allowable values are: default, top=0, left,=1 right=2, bottom=3.
Enter a value for this property only if you want to override the orientation
specified in the .portlet file. Selecting default removes the orientation
attribute from the portlet, book, and/or portlet instance; use this value if you want
to revert to the framework default setting for this attribute.
Portlet URI Required. The path (relative to the project) of the parent .portlet file. For
example, if the file is stored in Project\myportlets\my.portlet, the
Portlet URI is /myportlets/my.portlet.

Table 6-1 Portlet Instance Properties in the Properties View (Continued)

Property Value
Theme Optional. Select a theme to give the portlet a different Look & Feel than the rest
of the desktop.
Title Required. Enter a title only if you want to override the default title specified in the
.portlet file. The title is used in the portlet title bar.
Portlet titles cannot contain special characters such as & or #.
Portlet Properties in the Portlet Properties View

The properties described in this section are contained within the .portlet file and are editable
A
using the Workshop for WebLogic workbench. The values you enter here override the
corresponding value in the .portlet file, if a value exists there.
When you select the outer border of a portlet instance in the editor, a related set of properties
appears in the Properties view. The displayed properties vary according to the type of portlet that
ET
you are viewing. Figure 6-2 shows a portion of the Properties view for a portlet.
Figure 6-2 Properties View Example Showing Portlet Properties

B
Table 6-2 describes these properties and their values.

Table 6-2 Properties in the Portlet Properties View

Property Value
Backable Properties
Portlet Backing File Optional. If you want to use a class for preprocessing (for example,
authentication) prior to rendering the portlet, enter the fully qualified name of
that class. That class should implement the interface
com.bea.netuix.servlets.controls.content.backing.JspBacking or extend
com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking.
Content
Content Path Required. The path (relative to the project) to the file/class to be used for the
portlet's content. From the data field you can choose to browse to a file (or class
Error Page Path

is /myportlets/my.jsp. A
for Page Flow portlets) or open the currently displayed file/class. For example,
if the content is stored in Project/myportlets/my.jsp, the Content URI
Optional. The path (relative to the project) to the JSP or HTML file to be used
ET
for the portlet's error message if the main content cannot be rendered. For
example, if the error page is stored in Project/myportlets/error.jsp,
the Content URI is /myportlets/error.jsp.
General Portlet Properties
Async Content Allows you to specify the whether to use asynchronous content for a given
Rendering1 portlet and the implementation to use. An editable dropdown menu provides the
B
selections none, ajax, and iframe. Portlet files that do not contain the
asyncContent attribute appear with the initial value none displayed.
For more information, refer to “Asynchronous Portlet Content Rendering” on
page 7-5.
Cache Expires Optional. When the Render Cacheable property is set to true, enter the
(seconds) number of seconds after which the portlet cache expires.

Table 6-2 Properties in the Portlet Properties View (Continued)

Property Value
Cache Render This boolean property appears in the Properties view whenever a window portlet
Dependencies1 or proxy portlet is loaded, allowing render dependencies to be cached.
The value defaults to true if the attribute is not already included in the
.portlet file. The value is read-only for proxy portlets and editable by all
other portlet types. For proxy portlets, the value is initialized from the producer
whenever a proxy portlet is generated from the portlet wizard.
Client Classifications Optional. Select the multichannel devices using which the portlet can be viewed.
The list of displayed devices is obtained from the file
Project_Path\WEB-INF\client-classifications.xml. You must
create this file to map clients to classifications in your portal web project.
Guide.
A
For more information about this task, refer to the Portal Development
In the Manage Portlet Classifications dialog:

1. Select whether you want to enable or disable classifications for the portlet.
ET
2. Move the client classifications you want to enable or disable from the
Available Classifications to the Selected Classifications.
3. Click OK.
When you disable classifications for a portlet, the portlet is automatically
enabled for the classifications that you did not select for disabling.
Default Minimized Required. Select true if you want the portlet to be minimized when it is
B
rendered. The default value is false.
Definition Label Required. Unique identifier for the portlet. A default value is entered
automatically, but you can change the value. Each portlet must have a unique
value. Definition labels can be used to navigate to portlets. Also, components
must have Definition Labels for entitlements and delegated administration. The
length of the label must be 80 characters or less.
Description Optional. A short text description of the portlet. The description is displayed in
the Administration Console and Visitor Tools areas, and is sent from a WSRP
producer where applicable.
Event Handlers Optional. Use this value to configure interportlet commmunication using portlet
events. The default is No event handlers. Click Browse if you want to
select or add an event handler.


Property Value
Forkable Optional. Indicates whether or not the portlet can be multithread rendered. When
set to true, a portal administrator can use the Fork Render property to make the
portlet multithread rendered. The default is false.
For more information, refer to “Parallel Portlet Rendering” on page 7-3.
Fork Pre-Render Enables forking (multi-threading) in the pre-render lifecycle phase. (Refer to
“How the Control Tree Affects Performance” in the BEA WebLogic Portal
Overview for more information about the control tree life cycle.) Pre-render
forking is supported by these portlet types:
• JSP
• Page Flow
• JSR168
•
A
WSRP (consumer portlets only)
Setting Fork Pre-Render to true indicates that the portlet’s pre-render phase
should be forked.
ET
Fork Optional. If Fork Pre-Render is set to true, you can set an integer timeout value,
Pre-RenderTimeout in seconds, to indicate that the portal framework should wait only as long as the
(seconds) timeout value for each fork pre-render phase. The default value is -1 (no
timeout). If the time to execute the forked pre-render phase exceeds the timeout
value, the portlet itself times out (that is, the remaining life cycle phases for this
portlet are cancelled), the portlet is removed from the page where it was to be
displayed, and an error level message is logged that looks something like the
following example.
B
<May 26, 2005 2:04:05 PM MDT> <Error> <netuix>

<BEA-423350> <Forked render timed out for portlet
with id [t_portlet_1_1]. Portlet will not be included in
response.>
Fork Render Optional. Intended for use by a portal administrator when configuring or tuning
a portal. Setting to true tells the framework that it should attempt to multithread
render the portlet. This property can be set to true only if the Forkable property
is set to true.
Fork Render Timeout Optional. If Fork Render is set to true, you can set an integer timeout value, in
(seconds) seconds, to indicate that the portal framework should wait only as long as the
timeout value for each fork render portlet. The default value is -1 (no timeout).
When a portlet rendering times out, an error is logged, but no markup is inserted
into the response for the timed-out portlet.


Property Value
Orientation Optional. Hint to the skeleton to position the portlet title bar on the top, bottom,
left, or right side of the portlet. You must build your own skeleton to support this
property in the .portal file. Following are the numbers used in the .portal file for
each orientation value: top=0, left=1, right=2, bottom=3.
You can override the orientation in each instance of the portlet (in the Portal
Designer).
Packed Optional. Rendering hint that can be used by the skeleton to render the portlet in
either expanded or packed mode. You must build your own skeleton to support
this property.
When packed="false" (the default), the portlet takes up as much horizontal space
as it can.
A
When packed="true," the portlet takes up as little horizontal space as possible.
From an HTML perspective, this property is most useful when the window is
rendered using a table. When packed="false," the table's relative width would
likely be set to "100%." When packed="true," the table width would likely
ET
remain unset.
Render Cacheable Optional. To enhance performance, set to true to cache the portlet. For
example, portlets that call web services perform frequent, expensive processing.
Caching web service portlets greatly enhances performance.
Do not set this to true if you are doing your own caching.
For more information, refer to “Portlet Caching” on page 7-2.
B
Required User Optional. Possible values are none, all, or specified. If the value is
Properties Mode specified, then you must enter a list of property names in the field Required
User Properties Names field.
Required User Optional. Use this field if you entered a value of specified in the Required
Properties Names User Properties Mode field; enter a comma-delimited list of property names.
Title Required. Enter the title for the portlet's title bar. You can override this title in
each instance of the portlet (in the portal editor, as described in “Portlet
Properties in the Portal Properties View” on page 6-4).
Portlet titles cannot contain special characters such as & or #.
Page Flow Content


Property Value
Listen To Optional. The comma-separated list of instance labels of the portlets whose
actions should also be called in the selected page flow portlet.
Page Flow Action Optional. The initial action to be executed in a page flow. If not specified, the
begin action is used.
Page Flow Refresh Optional. The action to be executed in the page flow when the page is refreshed
Action but the portlet is not targeted. This is equivalent to using portlet event handlers
configured on the onRefresh portal event to invoke the page flow action.
Request Attribute Optional. Possible values are none, session, and transient-session.
Persistence This attribute controls attribute persistence for Page Flow, JSF, and Struts
portlets. The default is session, where request attributes populated by an
action are persisted into a collection class that is placed into a session attribute
A
so that the portal framework can safely include the forwarded JSP on subsequent
requests without re-running the action. Using the value session can cause
session memory consumption and replication that would not otherwise occur in
a standalone Page Flow, JSF, or Struts application. The value
ET
transient-session places a serializable wrapper class around a Hashmap
into the session. The value none performs no persistence operation.
Portlets that have the transient-session value applied generally have the
same behavior as existing portlets; however, in failover cases, the persisted
request attributes disappear on the failed-over-to server. In the failover case, you
must write forward JSPs to handle this contingency gracefully by, at a minimum,
not expecting any particular request attribute to be populated; ideally you should
include the ability to either repopulate automatically or present the user with a
B
link to re-run the last action to repopulate the request attributes. For non-failover
cases, request attributes are persisted, providing a performance advantage for
non-postback portlets identical to default session peristence portlets.
Portlets that have the none value applied will never have request attributes
available on refresh requests; you must write forward JSPs to assume that they
will not be available. You can use this option to completely remove the
framework-induced session memory loading for persisted request attributes.
Java Server Faces (JSF) Content
Request Attribute Refer to the description in the Page Flow Content section.
Persistence
Portlet Properties


Property Value
Content Presentation Optional. The primary uses are to allow content scrolling and content
Class height-setting.
For scrolling, enter a stylesheet class that uses one of the following attributes:
• overflow-y:auto - Enables vertical (y-axis) scrolling
• overflow-x:auto - Enables horizontal (x-axis) scrolling
• overflow:auto - Enables vertical and horizontal scrolling
For setting height, enter a stylesheet class that uses the following attribute:
• height:200px
where 200px is any valid HTML height setting.
You can also set other style properties for the content as you would using the
Presentation Class property. The properties are applied to the component's
Content Presentation
Style
content/child <div> tag.
A
Optional. The primary uses are to allow content scrolling and content
height-setting.
ET
For scrolling, enter one of the following attributes:
• overflow-y:auto - Enables vertical (y-axis) scrolling
• overflow-x:auto - Enables horizontal (x-axis) scrolling
• overflow:auto - Enables vertical and horizontal scrolling
For setting height, enter the following attribute:
• height:200px
B
where 200px is any valid HTML height setting.

You can also set other style properties for the content as you would using the
Presentation Style property. The properties are applied to the component's
content/child <div> tag.
Offer as Remote Optional. Defines whether the portlet is accessible using the WSRP producer.
The default is true, which allows the portlet to be accessed.
JSP Content


Property Value
Content Backing File

Optional. If you want to use a backing file for content prior to rendering the
portlet, enter the fully qualified name of the appropriate class. That class should
implement the interface
com.bea.netuix.servlets.controls.content.backing.JspBacking or extend
com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking.
Thread Safe Optional. Performance setting for books, pages, and portlets that use backing
files.
When Thead Safe is set to true, an instance of a backing file is shared among
all books, pages, or portlets that request the backing file. You must synchronize
any instance variables that are not thread safe.
Portlet Title Bar

A
When Thread Safe is set to false, a new instance of a backing file is created
each time the backing file is requested by a different book, page, or portlet.
ET
Can Delete Optional. If set to true the portlet can be deleted from a page.
Can Float Optional. If set to true the portlet can be floated into a separate window. For
instructions on creaeting a floatable Java portlet, which requires editing the
weblogic-portlet.xml file, in “Customizing Java Portlets Using
weblogic-portlet.xml” on page 5-16.
Can Maximize Optional. If set to true the portlet can be maximized.

B
Can Minimize Optional. If set to true the portlet can be minimized.
Edit Path Optional. The path (relative to the project) to the portlet's edit page.
Help Path Optional. The path (relative to the project) to the portlet's help file.
Icon Path Optional. The path (relative to the project) to the graphic to be used in the portlet
title bar. You must create a skeleton to support this property.
Mode Properties (available when you add a mode to a portlet)
Content Path Required. The path (relative to the project) to the JSP or HTML file to be used
for portlet's mode content, such as the edit page. For example, if the content is
stored in Project/myportlets/editPortlet.jsp, the Content URI is
/myportlets/editPortlet.jsp.


Property Value
Error Path Optional. The path (relative to the project) to the JSP or HTML file to be used
for the error message if the portlet's mode page cannot be rendered. For example,
if the error page is stored in Project/myportlets/errorPortletEdit.jsp, the Content
URI is /myportlets/errorPortletEdit.jsp.
Portlet Backing File Optional. If you want to use a class for preprocessing (for example,
authentication) prior to rendering the portlet's mode page (such as the edit page),
enter the fully qualified name of that class. That class should implement the
interface com.bea.netuix.servlets.controls.content.backing.JspBacking or
extend com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking.
Visible Optional. Makes the mode icon (such as the edit icon) in the title bar or menu
invisible (false) or visible (true). Set Visible to false when, for example,
Mode Toggle Button Properties
Name
A
you want to provide an edit URL in a desktop header.
Optional. Displayed when you select an individual mode. An optional name for
ET
the mode, such as Edit.
Presentation Properties
Presentation Class This property is described in the “Portal Properties” appendix of the Portal
Development Guide.
Presentation ID This property is described in the “Portal Properties” appendix of the Portal
Development Guide.
B
Presentation Style This property is described in the “Portal Properties” appendix of the Portal
Development Guide.
Properties Optional. A comma-delimited list of name-value pairs to associate with the

object. This information can be used by skeletons to affect rendering.
Skeleton URI This property is described in the “Portal Properties” appendix of the Portal
Development Guide.
Proxy Portlet Properties
Conenction Optional. The number of milliseconds after which this portlet will time out when
Establishment establishing an initial connection with its producer.
Timeout


Property Value
Connection Timeout Optional. The number of milliseconds after which this portlet will time out when
communicating with its producer. If not specified here, the default value
contained in the file WEB-INF/wsrp-producer-registry.xml is used.
Group ID Optional. If the producer associates this portlet within a group, the
producer-assigned string appears here. Portlets with the same group ID from the
same producer can share sessions.
Invoke Render This boolean property allows the consumer to obtain render dependencies from
Dependencies1 the producer during the pre-render life cycle of a proxy portlet.
When a portlet on a producer has a lafDependenciesUri value, the
producer exposes the invokeRenderDependencies boolean in the portlet
description.
A
The value defaults to false if the attribute is not included in the .portlet
file. The value is read-only, and is initialized from the producer whenever a
proxy portlet is generated from the portlet wizard.
ET
Portlet Handle Required. The producer’s unique identifier for the portlet that this proxy
references.
Producer Handle Required. The producer’s unique ideitifier.
Templates Stored in Indicates whether the producer stores URL templates in the user's session on the
Session producer side. This boolean is meaningful only when URL Template Processing
B
boolean is set to true.
URL Template Indicates whether the producer uses URL templates to create URLs. If true, the
Processing consumer supplies URL templates. If false, the producer rewrites URLs using
special rewrite tokens.
User Context Stored Required. This boolean value defaults to false if the attribute is not included
In Session1 in the .portlet file.
The value is read-only, and is initialized from the producer whenever a proxy
portlet is generated from the portlet wizard.
Struts Content


Property Value
Listen To (Deprecated) Allows this portlet to invoke an action when another portlet
invokes the same action. This functionality has been replaced with the more
complete interportlet communication mechanism.
Request Attribute Refer to the description in the Page Flow Content section.
Persistence
Struts Action The begin action that this struts portlet should invoke on the first request to the
portlet.
Struts Module The struts module that is associated with this struts portlet.
A "struts module" is a means of scoping a particular set of struts actions to a
group called a module, which generally maps to a single subdirectory of web
A
resources and a separate struts-config.xml file.
Struts Refresh Action Optional. The action to be performed in the struts module when the page
is refreshed but the portlet itself is not targeted.
ET
Uri Content (Browser portlet properties)
Content Url Required. The content control takes a URI that is expected to be a URL
for a standalone appliation or web page, and embeds the URL as portlet
content.
1. New in Version 9.2
B
Portlet Preferences
Portlet preferences provide the primary means of associating application data with portlets. This
feature is key to personalizing portlets based on their usage. This section describes portlet
preferences in detail.
After you create a portlet, you can instantiate it several times. Because you can create several
instances of a portlet, it is natural to expect each instance to behave differently yet use the same
code and user interface. For instance, consider a typical portlet to display a Stock Portfolio. Given
a list of stock symbols, this portlet retrieves quotes from a stock quote web service periodically,
and displays the quotes in the portlet window. By letting each user change the list of stock
symbols and a time interval to reload the quote data, you can let each user customize this portlet.

P ort le t P r ef ere nc es
The portlet needs to be able to store the list of stock symbols and the retrieval interval persistently,
and update these values whenever a user customizes these values. In particular, the following data
must be persistently managed:
z Default Values – Your portlet may specify a default list of stock symbols and a reasonable
retrieval interval. These values are applicable to all usages of the portlet no matter who the
user is. The user could even be anonymous.
z Customized Values – Your portlet also needs to be able to store these values when a user
updates the values for a given portlet instance. Note that your portlet should also scope this
data to an instance, such that other instances of this portlet are not affected by this
customization.
Technically, a portlet preference is a named piece of string data. For example, a Stock Portfolio
portlet could have the following portlet preferences:
z A
A preference with name “stockSymbols” and value “BEAS, MSFT”
Another preference with name “refreshInterval” and value “600” (in seconds).
You can associate several such preferences with a portlet. WebLogic Portal provides the
ET
following means to manage portlet preferences:
z Specify portlet preferences during the development phase

When you are building a portlet using the Workshop for WebLogic workbench, you can
specify the names and default values of preferences for each portlet. All portlet instances
derived from this portlet will, by default, assume the values specified during development.
z Let administrators modify portlet preferences

B
WebLogic Portal allows portal administrators to modify preferences for a given portlet
instance.This task occurs during the staging phase and uses the WebLogic Portal
Administration Console.
z Let portlets access and modify preferences at request time

At request time, your portlets can programmatically access and update preferences using a
javax.portlet.PortletPreferences object. You can create an edit page for your
portlet to let users update preferences, or you can automatically update preferences as part
of your normal portlet application flow.
z Specifying Portlet Preferences

z Using the Preferences API to Access or Modify Preferences
z Portlet Preferences SPI
z Best Practices in Using Portlet Preferences
Specifying Portlet Preferences

The steps to associate preferences with a portlet depend on the type of portlet you are building.
If you are using the Java Portlet API, described in “Getting and Setting Preferences for Java
Portlets Using the Preferences API” on page 6-24, the steps follow those specified in the Java
Portlet Specification. For other kinds of portlets, such as those using Java Page Flows, Struts, or
JSPs, you can use the Workshop for WebLogic workbench to add preferences to a portlet.
You can also allow the administrator to create new preferences using the Administration Console.
However, because the portlet developer is more likely to be aware of how portlet preferences are
phase. A
used by the portlet, it is more appropriate to create portlet preferences during the development
Specifying Preferences for Java Portlets in the Deployment Descriptor

ET
For portlets using Java Portlet API, you can specify preferences in the portlet deployment
descriptor. For all portlets in a web project, the deployment descriptor is portlet.xml, found in
the WEB-INF directory of the web project. Listing 6-1 provides an example.
Listing 6-1 Specifying Portlet Preferences in portlet.xml with a Single Value

B
<portlet>
<description>This portlet displays a stock portfolio.</description>
<portlet-name>portfolioPortlet</portlet-name>
<portlet-class>portlets.stock.PortfolioPortlet </portlet-class>
<supports>
<portlet-mode>edit</portlet-mode>
</supports>
<portlet-info>
<title>My Portfolio</title>
</portlet-info>
<portlet-preferences>
<preference>

<name>stockSymbols</name>
<value>BEAS, MSFT</value>
</preference>
<preference>
<name>refreshInterval</name>
<value>600</value>
</preference>
</portlet-preferences>
</portlet>
This snippet deploys the portfolio portlet with two preferences: a preference with name
stockSymbols and value BEAS, MSFT, and another preference refreshInterval with value 600.
A
Instead of specifying a single value for the stockSymbols preference, you can declare each
symbol as a separate value as shown in Listing 6-2 below, with the value elements shown in bold.
ET
Listing 6-2 Specifying Portlet Preferences with Values Specified Separately
<portlet>
<description>
This portlet displays a stock portfolio.
</description>
B
<portlet-name>portfolioPortlet</portlet-name>
<portlet-class>portlets.stock.PortfolioPortlet </portlet-class>
<supports>
</supports>
<portlet-info>
</portlet-info>

<preference>
<value>BEAS</value>
<value>MSFT</value>
</preference>
<preference>
<value>600</value>
</preference>
</portlet> A
ET
If you prefer that portlets should not be allowed to programmatically update any given
preference, you can mark the preference as read-only. Listing 6-3 shows an example of
preventing a portlet from changing the refreshInterval.
Listing 6-3 Specifying a Read-Only Portlet Preference Value

B
<portlet>
<description>
This portlet displays a stock portfolio.
</description>
<portlet-name>portfolioPortlet
<portlet-class>portlets.stock.PortfolioPortlet
<supports>

</supports>
<portlet-info>
</portlet-info>
<preference>
<value>BEAS</value>
<value>MSFT</value>
</preference>
<preference>
A
<value>600</value>
ET
<read-only>true</read-only>
</preference>
</portlet>
B
Note that by marking a preference read-only, you are preventing the portlet from changing the
current value only at request time. Portal administrators can always change the value(s) of a
preference using the Administration Console.
Specifying Preferences for Other Types of Portlets in Workshop for

WebLogic
If you are building other kinds of portlets (such as those using Java Page Flows, Struts, or simple
JSPs), you can add preferences using Workshop for WebLogic.
To add a preference, follow these steps:
1. Click to select the portlet for which you want to add a preference.

2. In the Outline view for the portlet, right-click Preferences and in the context menu click Add
Preference. Figure 6-2 shows an example of the preferences context menu.
Figure 6-2 Portlet Preferences Context Menu
A
ET
A new preference is added to the tree hierarchy with the name New Preference Preference.
3. Click the new item to display its properties in the Properties view.
4. Edit the values in the Properties view. Figure 6-3 shows an example of the fields in the
Properties view.
B
Figure 6-3 Portlet Preferences Properties View
Table 6-3 describes the attributes for portlet preferences as shown in the Properties view.

Table 6-3 Portlet Preference Properties

Field Value
Modifiable Indicates whether the preference is read-only or can be modified by

the user. The default is true.
Multi Valued Indicates whether the preference can have multiple values. The
default is true.
To specify multiple values for a preference, create multiple
preferences with the same name.
Description A brief description of the preference.
Name Name of the preference.
Value
A
Each preference can have one or more values. Each value is of type
java.lang.String.
ET
Using the Preferences API to Access or Modify Preferences
At request time, portlet preferences for a given portlet are represented as instances of the
javax.portlet.PortletPreferences interface. This interface is part of the Java Portlet API.
This interface specifies methods to access and modify portlet preferences.
Getting Preferences Using the Preferences API

B
Table 6-4 describes methods that allow a portlet to access its preferences.
Table 6-4 Methods that Allow a Portlet to Access its Preference Values
Method Purpose
String getValue(String name, String Use this method to get the first value of a preference.
default)
String[] getValues(String name, Use this method to get all the values of a preference.
String[] defaults)
boolean isReadOnly(String name) Use this method to determine whether a given
preference is read-only.

Table 6-4 Methods that Allow a Portlet to Access its Preference Values (Continued)
Method Purpose
Enumeration getNames() Use this method to get an enumeration of the names of
all preferences.
Map getMap() Use this method to get a map of preferences. The keys
in this map are the names of all the preferences, and
the values are the same as those returned by
getValues(String name, String[] defaults)
Setting Preferences Using the Preferences API

Table 6-5 describes methods that allow a portlet to change preference values.
Table 6-5 Methods that Allow a Portlet to Change Preference Values

Method
void setValue(String name, String
Purpose A
Use this method to set the value of a preference
ET
value)
void setValues(String name, Use this method to set several values for a preference
String[] values)
void store() Use this method to commit the changes made to preferences
for a portlet.
void reset(String name) Use this method to reset the value of a preference to its
B
default, or remove the preference if there is no default
After modifying preferences by calling setValue(), setValues() and reset() methods, you must call
store() explicitly to make the changes permanent; otherwise, changes will not be made
permanent.
Getting and Setting Preferences for Java Portlets Using the Preferences API
For portlets written using the Java Portlet API, you can obtain an instance of
javax.portlet.PortletPreferences object from the incoming portlet request –
javax.portlet.RenderRequest within the processAction() method, or
javax.portlet.ActionRequest within the render() method.

In Listing 6-4, the portlet displays a form to edit the the current values of portlet preferences in a
JSP page included from the doEdit() method of the portfolio portlet.
Listing 6-4
<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet"%>

<%@ page import="javax.portlet.PortletPreferences" %>
<portlet:defineObjects/>
<%
PortletPreferences prefs = renderRequest.getPreferences();
String refreshInterval = prefs.getValue("refreshInterval", "600");
%>
<form method="POST" action="">

A
String symbols = prefs.getValue("stockSymbols", "BEAS, MSFT");
ET
<table>
<tr>
<td>Symbols</td><td><input name="symbols" value="<%=symbols>"/></td>
</tr>
<tr>
<td>Refresh Interval</td><td><input name="refreshInterval"
value="<%=refreshInterval>"/></td>
B
</tr>
<tr>
<td></td>
<td><input type="submit" value="Submit"/></td>
</tr>
</table>
| </form>
The portlet updates the preferences in its processAction() method, as shown in Listing 6-5.

Listing 6-5
public class PortfolioPortlet extends GenericPortlet {

{
public void doEdit(RenderRequest renderRequest, RenderResponse
renderResponse)
throws IOException, PortletException
{
...
}
public void processAction(ActionRequest actionRequest, ActionResponse
actionResponse)
throws PortletException
{
String refreshInterval =
actionRequest.getParameter(“refreshInterval”); A
String symbols = actionRequest.getParameter(“stockSymbols”);
ET
PortletPreferences prefs = actionRequest.getPreferences();
prefs.setValue(“refreshInterval”, refreshInterval);
prefs.setValue(“stockSymbols”, symbols);
try {
prefs.store();
}
B
catch(SecurityException se) {
// Thrown when the user does not have enough privileges to store
preferences.
// Make sure that the user logged into the portal.
...
}
catch(catch(IOException ioe) {
// There is an error storing preferences
...
}
}
}

During processAction(), this portlet uses the javax.portlet.ActionRequest object to

obtain preferences.
Getting and Setting Portlet Preferences for Other Portlet Types

Portlet preferences can be accessed and updated from other kinds of portlets too. The main
difference is in the way your portlets obtain an instance of the
javax.portlet.PortletPreferences object.
z Render phase: During the render phase of a portlet (for example, in a JSP associated with a
Page Flow, or in the preRender() method of the backing file associated with the portlet),
portlets can use
com.bea.netuix.servlets.controls.portlet.PortletPresentationContext to
z
obtain portlet preferences.
A
Action phase: During the action phase of a portlet (for example, in a Page Flow action, or
in the handlePostbackData() method of the backing file associated with the portlet),
ET
portlets can use
com.bea.netuix.servlets.controls.portlet.PortletBackingContext to obtain
portlet preferences.
Both these classes provide a method getPreferences() that takes
javax.servlet.HttpServletRequest as an argument and return an object of type
javax.portlet.PortletPreferences.
B
JSP Tags for Getting Portlet Preferences

WebLogic Portal provides a JSP tag library for setting up portlet preferences. Table 6-6 describes
the applicable JSP tags.
Table 6-6 JSP Tags for Getting Portlet Preferences

Method Purpose
getPreference Use this tag to get the value of a portlet preference.
getPreferences Use this tag to get all the values of a portlet preference.
This tag can also used to write multiple values to the
output separated by a separator.

Table 6-6 JSP Tags for Getting Portlet Preferences

Method Purpose
forEachPreference Use this tag to iterate through all the preferences of a
portlet. You can nest other tags (getPreference,
getPreferences, ifModifiable and Else) inside this tag.
ifModifible Use this tag to include the body of this tag if the given
portlet preference is not read-only.
else Use this tag in conjunction with the ifModifiable tag to
include the body of this tag if the given portlet preference
is read-only
For more information on these tags, refer to the JSP Tag Reference. (Not available for Beta.)
Portlet Preferences SPI A

In WebLogic Portal, the framework includes a default SPI that manages portlet preferences in the
ET
PF_PORTLET_PREFERENCE and PF_PORTLET_PREFERENCE_VALUE database tables.
If desired, you can replace this implementation with your own.
You can use the Portlet Preferences SPI to allow portal applications to manage portlet preferences
outside framework-managed database tables. For example, you can store preferences along with
other application data in another back-end system or a different set of database tables.
The following sections describe how to use the Portlet Preferences SPI.
B
Implement the SPI

You specify the SPI using the interface com.bea.portlet.prefs.IPreferenceAppStore. An
implementation of this class must be deployed as a EJB jar file.
Listing 6-6 provides an example.
Listing 6-6 Implementing the SPI Using the Interface IPreferencesAppStore
public interface IPreferenceAppStore extends EJBObject

{
/**
* <p>Returns preferences for a portlet entity with the given
* <code>uniqueId</code>.</p>

*
* <p>The returned <code>java.util.Map</code> contains
* <code>com.bea.netuix.application.prefs.Preference</code>
* objects keyed against their names.</p>
*
* @param uniqueId unique ID
* @return preferences
*/
public Map getPreferences(PortletPreferencesId uniqueId) throws
RemoteException, PreferenceAppStoreException;
/**
* <p>Writes the preferences to the underlying persistence.</p>
*
* <p>This method should be implemented to be atomic. That is, the
* implemenation should guarantee that either all preference
* values are persisted or none at all.</p>
*
A
* <p>The <code>java.util.Map</code> argument should contain
* <code>com.bea.netuix.application.prefs.Preference</code>
* objects keyed against their names.</p>
*
ET
* @param uniqueId unique ID
* @param preferences preferences
*/
public void storePreferences(PortletPreferencesId uniqueId,
Map preferences) throws RemoteException, PreferenceAppStoreException;
/**
* <p>Clear all preferences for the given unique ID from the
B
* underlying persistence store.</p>

*
* @param uniqueIds unique IDs
*/
public void removePreferences(PortletPreferencesId[] uniqueIds) throws
RemoteException, PreferenceAppStoreException;
}
Using the SPI

To cause the framework to use a new SPI in place of the default SPI, you must update the EJB
named PreferencePersistenceManager in the ejb-jar.xml file within netuix.jar. The

value BEA_netuix.DefaultStore must be changed to the name of the SPI EJB as specified in
its deployment descriptor (ejb-jar.xml). The value
com.bea.portlet.prefs.provider.DefaultStoreHome must be changed to the home
interface of the SPI implementation.
The code segment in Listing 6-7 shows the default entries, which you must change to use the SPI.
Listing 6-7 Example Code Showing Default Entries that Must be Changed
<session>
<ejb-name>PreferencePersistenceManager</ejb-name>
<home>com.bea.portlet.prefs.PreferencePersistenceManagerHome</home>
<remote>com.bea.portlet.prefs.PreferencePersistenceManager</remote>
<ejb-class>com.bea.portlet.prefs.PreferencePersistenceManagerImpl
</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Container</transaction-type>
<env-entry> A
<env-entry-name>prefs-spi-jndi-name</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
ET
<env-entry-value>BEA_netuix.DefaultStore</env-entry-value>
</env-entry>
<env-entry>
<env-entry-name>prefs-spi-home-class-name</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>com.bea.portlet.prefs.provider.DefaultStoreHome
</env-entry-value>
</env-entry>
B


</session>
Best Practices in Using Portlet Preferences

Desktop Testing of Portlet Preferences
In order to view and test the preferences that you have created, you must use a desktop view from
the WebLogic Portal Administration Console rather than Workshop for WebLogic’s Portal >
Open Current Portal view.
Portlets accessed from .portal files cannot store preferences. If you access a portlet via a
.portal file, your portlet encounters a java.lang.UnsupportedOperationException error.

Users Must be Authenticated

Users who are updating portlet preferences must first be authenticated (logged in). If an
anonymous user attempts to update a portlet, a java.lang.SecurityException error occurs.
Note that portlets can always get portlet preferences irrespective of whether the user is
anonymous or whether the portlet is accessed via a .portal file.
Do Not Store Arbitrary Data as Preferences

It is tempting to store arbitrary application data as portlet preferences. For example, if you have
a portlet that allows users to upload and store documents on the server, it might seem appropriate
to store those documents as portlet preferences. This is not a good practice. The purpose of portlet
preferences is to associate some properties for a portlet instance without having to be aware of
any implementation-specific portlet instance IDs. These properties allow customization of the
portlet’s behavior. The underlying implementation of portlet preferences is not designed for
storing arbitrary application data.
A
The following steps outline an alternative implementation that can meet the needs of this portlet:
ET
Perform setup steps:
1. Add a preference to your portlet. This preference acts as the primary key to your portlet’s
application data. Assign a default value for this preference.
2. Create tables in your database to store application data with the value of the preference as the
primary key.
B
Set up preferences in your portlet:

1. When you want to associate application data with the current portlet instance, check the value
of the preference. If the value is the default, generate a new value (for example, using a
sequence number generator), and set this as the value of the preference, and store the
preference.
2. If the value of the preference is not the default, you do not need to generate a new value.
3. Store your application data using the value of the preference as the primary key.
This procedure ensures that your application data is always scoped to portlet instances.

Do Not Use Instance IDs Instead of Preferences

The portal framework maintains instance identity using internally generated instance IDs.
Portlets can access their instance IDs using getInstanceId() methods on
com.bea.netuix.servlets.controls.portlet.PortletPresentationContext and
com.bea.netuix.servlets.controls.portlet.PortletBackingContext.
Storing data directly in the database using portlet instance IDs does not work, for the following
reasons:
z The portal framework generates instance IDs, and portlets have no control over when and
how those instance IDs are generated.
z Instance IDs might change at any time without the portlet’s knowledge. For example, as
the user or administrator customizes a desktop using Visitor Tools or the Administration
Console, the framework can create new instances or change the instance ID of a portlet. If
A
the instance ID changes, your portlet cannot load the data from your database; the primary
key has changed without your portlet being aware of it.
Portlet Appearance and Features

ET
Some aspects of portlet appearance are controlled by default at the portal level, such as colors,
layouts, and themes. Appearance/rendering characteristics and portlet-specific features include
the use of title bars and associated states (minimize, maximize, float ,and delete) and modes that
affect portlet content (edit mode, help mode, and custom modes).
The following sections describe how to work with portlet-specific appearance/content features
and modes:
B
z Portlet Dependencies
z Portlet Modes
z Portlet States
z Portlet Title Bar Icons
z Portlet Height and Scrolling
Portlet Dependencies
The configuration of a Look & Feel has significantly changed in WebLogic Portal Version 9.2.
The concepts related to skin and skeleton resource dependencies are now more formally known

Por t let A pp ear a nce an d Fea tu r es
as render dependencies and script dependencies. Typical examples of such dependencies are CSS
files and JavaScript files.
Both skins and skeletons may now specify such dependencies as well as associated search paths
to be used for resolving these dependencies. Additionally, mechanisms exist to eliminate
redundancy and to provide a reliable ordering for dependencies related to skins, skeletons, and
theme skin and skeletons. These same capabilities are now available for portlets as well as
portals, so that a portlet can specify necessary dependencies in a standards-compliant way; you
identify these dependencies using appropriate elements located in the head section of the
rendered page. The other advantages of the Look & Feel dependencies framework are also
realized at a portlet level, such as reliable ordering and redundancy elimination.
z Identifying Portlet Dependencies
z Considerations and Limitations
Identifying Portlet Dependencies

A
The configuration of portlet dependencies shares the same mechanisms as the standard Look &
ET
Feel—you use an XML configuration document conforming to a standard Look & Feel schema.
This XML document is referenced from a .portlet file using an attribute on the portlet element.
As with a Look & Feel’s render dependencies, you can resolve a portlet’s render dependencies
utilizing a set of application search paths. Additionally, the search paths of the Look & Feel skin,
or any appropriate Theme skin, are used before the portlet’s own search paths to resolve a
portlet’s render dependencies.
B
You specify a portlet’s dependencies configuration file by adding the attribute

lafDependenciesUri to the portlet element in a .portlet file, as follows:
<netuix:portlet definitionLabel="myPortlet" title="My Portlet"
lafDependenciesUri="myPortlet.dependencies">
By convention, you should adhere to the following guidelines when setting up a portlet’s
dependencies configuration file:
z Give the file the same name as the .portlet file.
z Assign the file a .dependencies extension.
z Locate the next in the same level in the file hierarchy as the .portlet file.

Although the guidelines listed here are not required, deviating from them can lead to unexpected
behavior. For more information, refer to “Considerations and Limitations” on page 6-35.
The portlet dependencies configuration file uses standard types from the standard Look & Feel
schemas and looks similar to the example shown in Listing 6-8.
Listing 6-8 Portlet Dependencies Configuration File Example
<?xml version="1.0" encoding="UTF-8"?>

<laf:portlet
xmlns:laf="http://www.bea.com/servers/portal/framework/laf/portlet/1.0.
0"
xmlns:base="http://www.bea.com/servers/portal/framework/laf/base/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bea.com/servers/portal/framework/laf/
portlet/1.0.0 laf-portlet-1_0_0.xsd">
<laf:render-dependencies>
<base:html>
<base:links>
<base:search-path>
A
ET
<base:path-element>css</base:path-element>
<base:path-element>.</base:path-element>
</base:search-path>
<base:link rel="stylesheet" type="text/css" href="simple.css"
/>
<base:link rel="stylesheet" type="text/css" href="a.css" />
</base:links>
<base:scripts>
B
<base:search-path>
<base:path-element>js</base:path-element>
<base:path-element>.</base:path-element>
</base:search-path>
<base:script type="text/javascript" src="simple.js" />
<base:script type="text/javascript" src="a.js" />
</base:scripts>
</base:html>
</laf:render-dependencies>
</laf:portlet>
The configuration file shown in Listing 6-8 causes two CSS files and two JavaScript files to be
included in the rendered page output (as link elements in the HTML head section). First, the
search occurs for the CSS files relative to the Look & Feel or Theme skin search paths for the

links element. If the CSS files are not found, then the search path in the configuration file is used.
Relative search paths use the directory of the configuration file as a base.
Similarly, the two specified JavaScript files are searched for, using the Look & Feel or Theme
skin search paths for scripts, and if not found the search path specified in the configuration file is
used.
Situations may arise where you do not want the default behavior, which is to look first in the Look
& Feel or Theme specified search paths. In such situations, you can disable this behavior by
specifying a value of false for the use-skin-paths attribute on the render-dependencies
element.
Considerations and Limitations

At this time, Workshop for WebLogic does not providing editing capabilities for portlet render
dependencies configuration files; you can use any XML file editor for this purpose.
A
BEA recommends that you not share a single .dependencies file across several portlets.
Although WebLogic Portal does not prevent this usage, and sharing a single file might seem to
be a prudent plan, this configuration might cause difficulties later when .dependencies file
ET
editing capability becomes available in the workbench GUI; it would be difficult for an editing
interface to coordinate updates to a shared configuration file.
Portlet dependencies are not currently supported by WSRP.
The Look & Feel portal framework for render dependencies includes the capability to render an
external dependency directly in the page output by specifying the contentUri attribute for a
dependency. This capability is currently not supported for portlets.
B
Portlet Modes
All portlets created with WebLogic Portal support the use of modes. Modes allow you to affect
the end user’s ability to edit the portlet or display Help for the portlet. You add icon buttons to a
portlet’s title bar to indicate the availability of a mode.
The following pre-defined modes exist for WebLogic Portal:
z Edit – Lets you specify a custom file that lets users modify the portlet's content when they
click the Edit button.
z Help – Lets you specify a custom file that shows users help content for the portlet when
they click the Help button.
You can also create your own custom portlet modes using WebLogic Portal.

Buttons for the selected modes appear in the portlet’s title bar. Figure 6-4 shows an example of
the default buttons for the portlet modes when displayed in the editor; Figure 6-5 shows the
appearance of the mode icons in a running portlet.
Figure 6-4 Portlet Mode Buttons in Editor
Minimize Maximize Delete Float Help Edit
A
ET
Figure 6-5 Portlet Mode Buttons in a Running Portlet
Minimize Maximize Delete Float Edit Help

B
When you use the Portlet Wizard to create a portlet, mode and state settings are available on the
Portlet Details dialog. These settings can also be edited in the portlet’s Properties view: The
following sections describe possible methods of performing these tasks.
Adding or Removing a Mode for an Existing Portlet

To add or remove the Help or Edit mode from the title bar, follow these steps:
1. Display the portlet for which you want to add or remove a mode.

2. Right-click the title bar of the displayed portlet to display the context menu. Figure 6-6 shows
an example of the title bar context menu.
Figure 6-6 Available Portlet Modes - Title Bar Context Menu
A
ET
3. Click Available Modes.
Checkmarks on the submenu indicate the available modes for this portlet, which were
determined when you created it. Figure 6-7 shows an example of the submenu.
Figure 6-7 Portlet Mode - Available Modes Submenu

B

4. Click the mode for which you want to change the availability status. For example, in
Figure 6-7, the Help mode is checked (available); when you click Help, the Help button
disappears from the title bar.
5. Select File > Save to save your changes.
Properties Related to Portlet Modes

You can view and edit the mode's property details in the Properties view. For example, you can
edit the Portlet Backing File property if you want to perform preprocessing before rendering the portlet's
mode page (such as the edit page).
To display the mode properties for the portlet, click the expand/contract toggle button in the
Portlet Mode area of the portlet. Edit mode properties and Help mode properties display in the
Properties view.
A
For descriptions of the mode properties, refer to Table 6-2.
Portlet States
ET
States determine the end user’s ability to affect the rendering of a portlet. WebLogic Portal
supports these portlet states:
z Minimize – Collapses the portlet, leaving only the title bar, when the user clicks the
Minimize button.
z Maximize – Makes the portlet take up the entire desktop area (not including the desktop
header and footer) when the user clicks the Maximize button.
B
z Float – Displays the portlet in a popup window when the user clicks the Float button.
z Delete – Removes the portlet from the desktop when the user clicks the Delete button.
When you use the Portlet Wizard to create a portlet, state and mode settings are available on the
Portlet Details dialog. These settings can also be edited in the portlet’s Properties view: The
following sections describe possible methods of performing these tasks.
Modifying Portlet States

You can select which of the states you want to include with the portlet by following these steps:
1. Right-click the portlet title bar.

A context menu showing applicable states appears. Figure 6-8 shows an example of the
title bar context menu showing all states as available.
Figure 6-8 Portlet State - Title Bar Context Menu
A
ET
2. Click to select the state that you want to change.
Selecting a state adds it to the portlet, while deselecting the state removes it from the
portlet. For example, in Figure 6-8, all four states are selected, and appear in the title bar. If
you click to deselect Deletable, the Delete button on the portlet disappears.

B
Portlet Title Bar Icons

This section TBD.
Portlet Height and Scrolling

All portlets created with WebLogic Portal support height and scrolling.
z Height affects the portlet’s displayed height on the portlet page.
z Scrolling affects whether or not the portlet is scrollable.

You can control the height of portlets and determine whether or not their contents scroll.
Portlet height and scrolling is controlled by the following CSS style attributes:

z {overflow-y:auto} – Enables vertical (y-axis) scrolling
z {overflow-x:auto} – Enables horizontal (x-axis) scrolling
z {overflow:auto} – Enables vertical and horizontal scrolling
z {height:200px} (where 200px is any valid HTML setting)

You can set these attributes on a portlet that is open in the workbench editor.
To set these properties, follow these steps:
1. Open a portlet in the the workbench editor.
2. Click the outer border of the portlet to display the portlet properties in the Properties view.
3. In the Properties view, set one of the following properties:

– Presentation Style - Enter any of the previously listed attributes for this property. You
A
can use overflow and height. Separate the values with a semicolon.
– Presentation Class - Enter the name of a style sheet class that contains the height or
scrolling attributes that you want to use.
ET
Figure 6-9 shows an example of possible height and scrolling properties, set using
Presentation Style.
Figure 6-9 Portlet Height and Scrolling Presentation Properties Example

B
Based on the entries shown in Figure 6-9, the result looks similar to the example in
Figure 6-10.

Figure 6-10 Portlet Height and Scrolling - Portlet Appearance Results
If you use the Presentation Class property instead of the Presentation Style property, you
must have the corresponding style class defined in a CSS file.
For example, if you use the value portlet-scroll in the Content Presentation Class field,
you must have the following style class definition already set up in your CSS file:
portlet-scroll
{
overflow-y:auto;
A
ET
height:250px;
}
Making All Portlets Scroll

B
To provide portlet height or scrolling automatically, you can also modify the window.jsp file in
each skeleton to incorporate a CSS style or class.
Note: The window.jsp file is stored in a WebLogic Portal library module; if you want to
change it you can copy it to the project. For more information about copying library
module files to a project, refer to the Portal Development Guide.
For example, in the default skeleton's window.jsp, do one of the following:
z Replace the string bea-portal-window-content with the name of the scrolling portlet
style class you created, such as portlet-scroll. (Be sure the CSS file containing the
scrolling class is registered in the skin's skin.properties or skin_custom.properties
files.)
z In the last line of the JSP, change

style value="<%= window.getContentPresentationStyle() %>" />

to
style value="<%= window.getContentPresentationStyle() %>"
defaultValue="{overflow-y:auto};{height:250px}" />
You could also modify the skin CSS style class. For example, in the skin's window.css file, you
can define the bea-portal-window-content class like this:
.bea-portal-window-content
{
margin: 4px;
padding: 0px;
scrollbar-base-color: #d8d8e5;
overflow-y: auto;
height: 250px;
}
A
For more information on portal skins, themes, and skeletons, refer to the Portal Development
Guide.
ET
JSPs, JSP Tags, and Controls in Portlets
WebLogic Portal provides JSP tags that you can use within JSPs. Portlets can use JSPs as their
content nodes, enabling reuse and facilitating personalization and other programmatic
functionality. You can create JSPs with Workshop for WebLogic to provide a structure for other
elements to be added to a portlet.
B
Workshop for WebLogic also provides Java controls that make it easy for you to encapsulate
business logic and to access enterprise resources such as databases, legacy applications, and web
services. Three different types of Java controls are available: built-in Java controls, portal
controls, and custom Java controls.
The following sections describe these portlet creation tools in more detail:
z JSP and JSP Tags in Portlets
z Portal Controls Introduction

J SP s, JS P Tag s, an d Co nt ro ls in Por t let s
JSP and JSP Tags in Portlets

When you use the JSP Design Palette view in Workshop for WebLogic, you can view available
JSP tags and then drag them into the Source View of your JSP, and use the Properties view to edit
elements of the code.
When you open a JSP in Workshop for WebLogic, you can use the JSP Design Palette (Window
> Show View > JSP Design Palette) to display all the JSP tags currently loaded and available;
Figure 6-11 shows a portion of the display.
Figure 6-11 JSP Design Palette Showing Available JSP Tags
A
ET
B
To use a tag, drag it into the editor, use the Source View to edit the code directly, and use the
Properties view to set properties, as shown in Figure 6-12:
Figure 6-12 Dragging a JSP into the Design View

Much of the functionality exposed by the WebLogic Portal JSP tags has been organized into even
simpler objects called controls. This means that most user management functionality, for
example, can be easily exposed with a User Manager Control on a page flow. For details about
controls, refer to the Javadoc .
The following links <TBD> offer more detailed information about using JSP tags: :
z JSP Tag Wizards – When dragged into the Portal Designer, certain Portal JSP tags invoke
wizards that automatically populate important tag attributes in your JSP.
z JSP Tag Reference – The tag libraries provided for developing web applications on
WebLogic Platform are documented extensively.
z Page Flow Reference – To use page flows effectively, familiarize yourself with
annotations, icons, exception handling, and data binding. Actions defined in a page flow
can be called from within a JSP, and vice-versa. These calls can be invoked by dragging
action icons into the design view of your JSP.
Portal Controls Introduction

This section TBD.
A
ET
Portlet Events
Portlet events (not to be confused with page flow events) allow portlets to communicate. One
portlet can create an event and other portlets can listen for that event. A portlet event can also
carry accompanying data called a payload.
B
Interportlet communication (IPC) depends on the use of event handlers—Java objects that listen
for a predefined event on other portlets in the portal and fire actions when that event occurs. For
more information on interportlet communication and example scenarios of IPC setup, refer to
Chapter 8, “Interportlet Communication.”
z Event Handlers
z Event Types
z Event Actions
z Portlet Event Handlers Wizard Reference

P o r tl e t Eve nt s
Event Handlers
Event handlers listen for events raised on subscribed portlets and fire an action when a specific
event is detected. The following sections describes each of the event handlers available with
WebLogic Portal and describes how that handler works.
TBD
Event Types
An event action depends upon the type of event being raised. Except for portal events, all other
events can be identified in the Events field on the Portlet Event Handlers Wizard, as described in
“Portlet Event Handlers Wizard Reference” on page 6-47. Events available with the portal event
handler are listed in Table 6-7.
onActivation
A
Table 6-7 Events Available to a Portal Event Handler
This event... Fires an action when the portlet...
Becomes visible
ET
onDeactivation Ceases to be visible
onMinimize Is minimized
onMaximize Is maximized
onNormal Returns to its normal state from either a maximized or minimized state
B
onDelete Is deleted from the portal
onHelp Enters the help mode
onEdit Enters the edit mode
onView Enters the view mode
onRefresh Is refreshed
onCustomEvent Mode change to the custom mode CustomEvent

Refer to Custom Events.

Custom Events
A custom event is an event that you define. A custom event can pass a developer-defined payload
or fire any predefined action. Custom events can be fired declaratively or they can be based on a
methods called in a backing file. You can specify that an event should be handled by a method in
a backing file.
For an example of how to use a custom event to set up interportlet communication, refer to “IPC
Example with Custom and Page Flow Event Handlers” on page 8-17.
Page Flow Events

A page flow event is any occurrence during a page flow life cycle that can trigger an action on
another portlet. For example, if a user submits authentication information using a login portlet
that uses a page flow, submission of the login form can signal listening portlets to query various
databases and return information specific to the authenticated user and specific to the listening
portlets.
A
For an example of how to use a page flow event to set up interportlet communication, refer to
“IPC Example with Custom and Page Flow Event Handlers” on page 8-17.
ET
Event Actions
Event handlers fire an action on the host portlet when that handler detects an event from another
portlet in the application; for example, when the user minimizes the appropriate portlet, a portal
event called onMinimize might cause the handler listening for it to fire an action that invokes an
attached backing file.
B
Table 6-8 lists the event actions available for portlets.
Table 6-8 Event Actions

This action... Has this effect...
Change Window Mode Changes the mode from its current mode to a user-specified mode; for
example, from help mode to edit mode.
Change Window State Changes the state from its current state to a user-specified state; for
example, from maximized to delete state.
Activate Page Opens a user-specified page.
Fire Generic Event Fires a user-specified generic event.

Table 6-8 Event Actions

This action... Has this effect...
Fire Custom Event Fires a user-defined custom event. This event needs to be included in the
portlet file.
Invoke BackingFile Runs a method in the backing file attached to the portlet. For more
Method information on backing files, refer to “Backing Files” on page 7-10.
Portlet Event Handlers Wizard Reference

The Portlet Event Handlers wizard included in Workshop for WebLogic allows you to implement
several types of event handlers and actions without programming. The following steps
summarize the process of setting up an event handler or action using the wizard:
1. Select a type of event handler to create.

A
2. Determine the portlet(s) to which that handler will listen.
3. Select an event for which the handler will listen.

ET
4. Select and configure an action to fire when the event occurs.
The following sections describe the dialogs of the wizard and provide information about the
information required in each field of the dialogs.
For a specific procedural example of how to use the event handler wizard, refer to“Basic IPC
Example” on page 8-4.
B
Portlet Event Handlers Wizard Dialogs

The wizard opens when you open a portlet in Workshop for WebLogic and click the ellipses
button (...) next to Event Handlers in the Properties view.
Note: If no event handlers have been added, the Event Handler field indicates that. If any event
handlers have been added, the field indicates the number added.
The wizard appears, as shown in Figure 6-13.

Figure 6-13 Portlet Event Handlers Wizard
A
When you click Add Handler, the event handler drop-down menu allows you to select a handler;
to add an action, click Add Action to open the event action drop-down menu.
ET
Based on your selection, the dialog box expands, displaying additional fields that you can use to
set up the handler or action. Figure 6-14 shows an example of the expanded dialog for adding an
event handler.
Figure 6-14 Expanded Event Handlers Dialog

B

Portlet Event Handlers Wizard - Add Handler Field Descriptions

Table 6-9 explains the fields in the Add Handler dialog and how your selections affect the
behavior of the event.
Table 6-9 Portlet Event Handlers Wizard - Add Handler

Field Description
Event Label Required. This identifier can be used by the <filterEvent> tag in the
portal file to distinguish multiple event handlers in the same portlet. The
value should be unique across all event handlers in the portlet.
Description Optional. Provides a description so that users can decide which portlet(s)
this portlet should listen to.
Only If Displayed Optional. Indicates that the portlet to receive the event must be on the
checkbox
A
current page and not minimized or maximized. In other words, “Only If
Displayed” indicates that in order to generate an event, the portlet’s content
must be currently in a rendered state. If you check this box and your portlet
is minimized or maximized, it will not receive the event. The default is
ET
true.
Note: If you have checked the Only If Displayed box and an entitlement
setting for the portlet causes it not to be visible, then the portlet
does not receive the event.
Note: If the event is <handlePortalEvent event="onMinimize"

fromSelfInstanceOnly="true"> then it is logically impossible for
this event to fire if onlyIfDisplayed="true".
B
From Self Instance Only Optional. Defines whether the handler for a given portlet instance is
checkbox invoked only when the source event originates from that instance. The
default is false.
If From Self instance Only is set to true, any Listen To values are ignored.

Table 6-9 Portlet Event Handlers Wizard - Add Handler (Continued)

Field Description
Listen To (wildcard) Optional. Identifies the portlet(s) that this portlet can listen to. The values
include:
• This - the definition label of this portlet
• None
• Any
Note: Currently, None and Any are functionally equivalent.
Note: If both Listen to (wildcard) and Listen To (portlets) are defined, the
system will “union” their values during processing; that is, if the
wildcard is “this,” then the owning poretlet definition lablel wil be
added to those in Listen To (portlets), and if the wildcard is ‘any”
then the value of Listen To (portlets) is ignored.
Listen To (portlets)
A
Optional. Allows you to specify the portlets that this portlet can listen to.
You can choose a .portlet file from the file system by clicking the '...'
button). When you select a .portlet file and hit Open, the portlet is added to
the definitionLabels JPanel.
ET
Note: When you click Open, the definition label is also added to the
specificLabels JLabel and the Add button enables.Although the
enabled Add button might make it appear that the portlet still needs
to be added, it does not.
Portlet You can type a portlet name in the field and click Add, or click the browse
button to navigate to the portlet that you want to listen to.
B
Event Use the dropdown menu to select an event that the portlet should listen for.
Portlet Event Handlers Wizard - Add Action Field Descriptions

The available fields for the action depend on the type of action that you select. Table 6-10
explains the possible fields in the expanded Add Action dialog and how your selections affect the
behavior of the action.

E rr o r H a nd l i n g
Table 6-10 Portlet Event Handlers Wizard - Add Action

Field Description
Action Label
Description
xxx Activate Page Action - This action will activate the page on which portlet
<portlet_def_id> currently resides.
Note: Do not select the Activate Page action if the Only If Displayed
box is checked. Logically, if the portlet is only responding to the
event if it is displayed, the page that it is on must be active
anyway.
xxx
Error Handling
A
ET
This section not available for beta.
Portlet State Persistence

You can control portlet state persistence using the persistence-enabled attribute in the
netuix-config.xml file. Using this attribute causes the state to be saved in the the WebLogic
Portal database.
B
The following code segment shows an example of the attribute syntax:

<control-state-location>
<session persistence-enabled="true"/>
</control-state-location>
WebLogic Portal places an entry for the control tree state in the PROPERTY_KEY table, with
the following PROPERTY_SET_NAME value:
z BEA_PORTAL_FRAMEWORK_CONTROL_TREE_STATE
For a complete description of the attributes in the netuix-config.xml, you can refer to the
appropriate appendix of the Portal Development Guide.

Adding a Portlet to a Portal

Note for Beta Release - Some of the tasks in this section are described in a “tutorial” format
based on the Getting Started with WebLogic Portal tutorials. The descriptions of these tasks will
be expanded for the GA release.
In the development phase of the portal life cycle, you add portlets to a portal using the Workshop
for WebLogic editor.
In this task you will add your new portlets to the portal and view your changes.
Note: A Page must have a layout before you can add a portlet to it. The vertical or horizontal
placement of portlets in a placeholder is determined by the selected layout for the page.
Follow these steps:
1. In the editor, click the myPortal.portal tab to display it.
2. Click the Page 1 tab in the portal to select it.

A
3. Drag the JSP portlet (with the file name jsp_portlet.portlet) onto the left column of the portal
page.
ET
4. Drag the Browser portlet (with the file name myBrowserPortlet.portlet) onto the right column
of the portal page.
Your result should look like the example in Figure 6-1.
B

A dd i ng a Po rt l e t t o a P o r ta l
Figure 6-1 Portal in Editor View with Portlets Added
A
ET
5. With the portlet selected, go to the Properties view to customize desired portlet properties if
desired.
For detailed information about portlet properties, refer to “Portlet Properties” on page 6-1.
B
6. Save the portal file.

When you add a portlet to a page in the workbench editor, a reference to that portlet is added to
the .portal file. The .portal file is a template that can be used to create desktops in the
WebLogic Portal Administration Console. When a portal administrator creates a desktop based
on that template, the portlet is added to the portal resource library where it can be added to pages
in streaming desktops. For an overview of file-based portals compared with streaming portals,
refer to the Portal Development Guide.
In the Staging phase of the portal life cycle, you use the WebLogic Portal Administration Console
to configure portlets on desktops. A single portlet definition can be associated with one or more
portals (desktops) by creating instances of the portlet. Each of these portlet instances can have its
own “personality” and behavior as specified by a variety of different configuration options.

For details in adding a portlet to a portal desktop in the WebLogic Administration Portal, refer to
“Add a Portlet to a Page in the Staging Environment” on page 9-2.
Removing and Deleting Portlets

To remove a portlet from a portal (without deleting the portlet from your portal web project),
right-click the portlet in the Workshop for WebLogic workbench editor and click Delete.
To delete a portlet from your portal web project, right-click the portlet in the Package Explorer
view and choose Delete.
To remove a portlet after you have assembled portlet instances into portal desktops, refer to
<TBD> .
A
ET
B

CHAPTER 7
Optimizing Portlet Performance
A
The process of optimizing your portlets for the best possible performance spans all phases of
development. You should continually monitor performance and make appropriate adjustments.
This chapter describes performance optimizations that you can incorporate as you develop
portlets.
ET
z Performance-Related Portlet Properties
z Portlet Caching
z Remote Portlets
B
z Parallel Portlet Rendering
z Asynchronous Portlet Content Rendering
z Backing Files
Performance-Related Portlet Properties

Customizing performance-related portlet properties can help you improve performance. For
example, you can set process-expensive portlets to pre-render or render in a multi-threaded
(forkable) environment. If a portlet has been designed as forkable (multi-threaded) you have the
option of adjusting that setting when building your portal.
The following portlet properties are performance related:

O pt i m i z i n g Por t l e t P e r fo r m a nce
z Render Cacheable/Cache Expires
z Forkable/Fork Render/Fork Render Timeout
z Fork Pre-Render/Fork Pre-Render Timeout
z AsyncContent
“Portlet Properties” on page 6-1 includes descriptions of these properties. If you design your
portlets to allow portal administrators to adjust cache settings and rendering options, you can
modify those properties in the Administration Console.
Portlet Caching
You can cache the portlet within a session instead of retrieving it each time it recurs during a
session (on different pages, for example). Portlets that call web services perform frequent,
A
expensive processing; caching web service portlets greatly enhances performance. Portlet
caching is well-suited to caching personalized content; however, it is not well suited to caching
static content that is presented identically to all users and that rarely expires.
The ideal use case of the portlet cache is for content that is personalized for each user and expires
ET
often. Other use cases should look to more appropriate caching alternatives such as the use of the
wl:cache tag or the portal cache.
Remote Portlets
While you can reduce development time by using a remote portlet—because you don't have to
B
actually develop the contents of the portlet, merely its container—the major performance benefit
is that any controls within the application (portlet) that you are retrieving are rendered by the
producer and not by your portal. The expense of calling the control life cycle methods is borne
by resources not associated with your portal.
Implementing proxy, or remote, portlets might result in some performance improvement,
although this method also comes with its limitations. Remote portlets are made possible by Web
Services for Remote Portlets (WSRP), a web services standard that allows you to “plug-and-play”
visual, user-facing web services with portals or other intermediary web applications. It allows
you to consume applications from WSRP-compliant Producers, even those far removed from
your enterprise and surface them in your portal.
For more information on implementing remote portlets with WSRP, refer to the WebLogic Portal

Paralle l Portl et Rendering
How Remote Portlets Provide a Performance Boost

While you can reduce development time by using a remote portlet—because you do not have to
actually develop the contents of the portlet, just its container—the major performance benefit is
that any controls within the application (portlet) you are retrieving are rendered by the producer
and not by your portal. The expense of calling the control life cycle methods is borne by resources
not associated with your portal.
Although using remote portlets can improve portal performance, it is not without its drawbacks.
For example:
z Fetching data from the producer can be expensive. You need to decide if that expense is
within reason given the resources locally available.
z Some features, such as customizations, are unavailable to the remote portlet.

If the expense of portal rendering sufficiently offsets the expense of transport and the other
A
limitations described above are inconsequential to your application, using remote portlets can
provide some performance boost to your portal.
ET
Parallel Portlet Rendering
You can cause process-expensive portlets to render in a multi-threaded (forkable) environment.
If a portlet has been designed as forkable (multi-threaded) you have the option of adjusting that
setting when building your portal. This can increase performance of portlets whose processing
can be time-extensive, such as RSS feeds. The following sections describe how to implement
pre-render and render forking:
B
z Pre-Render Forking
z Render Forking
Pre-Render Forking
The attribute forkPreRender enables forking (that is, multithreading) in the pre-render lifecycle
phase. (Refer to “How the Control Tree Affects Performance” in the BEA WebLogic Portal Overview for
more information about the control tree life cycle.) Setting forkPreRender to true indicates that the
portlet’s pre-render phase should be forked. As with render phase forking, pre-render phase
forking is only possible if the portlet’s forkable attribute is set to true.
Pre-render forking is supported by these portlet types:

z JSP
z Page Flow
z JSR168
z WSRP (Consumer portlets only)

To enable pre-render forking for each portlet type, edit the following portlet properties in the
Properties view:
z Forkable
z Fork Pre-Render
z Fork Pre-Render Timeout
z Fork Timeout (optional)

For a description of each property, refer to Table 6-2.
Render Forking
A
ET
The attribute forkRender enables forking (that is, multithreading) in the render lifecycle phase.
Setting forkRender to true indicates that the portlet’s render phase should be forked. As with
pre-render phase forking, render phase forking is possible only if the portlet’s forkable attribute
is set to true.
Render forking is supported by these portlet types:
B
z JSP
z Page Flow
z JSR168
z WSRP (Consumer portlets only)

To enable render forking for each portlet type, edit the following portlet properties in the
Properties view:
z Forkable
z Fork Render
z Fork Render Timeout

Asyn c hro n o u s P o rtl e t Co nt e n t Re nd e ring
z Fork Timeout (optional)

For a description of each property, refer to Table 6-2.
Asynchronous Portlet Content Rendering

z Considerations for IFRAME-based Aynchronous Rendering
z Considerations for AJAX-based Asynchronous Rendering
z Comparing IFRAME- and AJAX-based Aynchronous Rendering
z Portal Life Cycle Considerations with Asynchronous Content Rendering
z Asynchronous Content Rendering and IPC
A
Asynchronous portlet rendering allows you to render the content of a portlet independently from
the surrounding portal page. You can use either AJAX technology or IFRAME technology to
implement asynchronous rendering. When using asynchronous portlet rendering, a portlet
renders in two phases. The normal portal page request process occurs first; during this process,
ET
the portlet's non-content areas, such as the title bar, are rendered. Rather than rendering the actual
portlet content, a placeholder for the content is rendered. A subsequent request process displays
the portlet content.
A new portlet property asyncContent in the Properties view allows you to specify whether to
use asynchronous rendering, and to select which technology to use. An editable dropdown menu
provides the selections none, ajax, and iframe. If you want to create a customized
B
implementation of asynchronous rendering, you can do so by editing the .portlet file to set this
up; more information about this task will be available in a dev2dev article in the future.
Portlet files that do not contain the asyncContent attribute appear with the initial value none
displayed in the Properties view. Any changes to the setting are saved to the .portlet file.
Note: Although Browser portlets use an internal implementation that appears similar to that of
an asynchronous portlet and both portlet types use IFRAME HTML elements, the actual
implementations are quite different. Browser portlets are merely displaying static
embedded documents, but asynchronous IFRAME portlets are managed by the
framework.
Keep the following global considerations in mind for any asynchronous rendering
implementation:

z As a best practice, do not depend on browser-based navigation. Build navigation into your
portlets so that navigation is handled at that level of interaction.
If navigation is handled by the browser, the behavior of a portlet will vary according to the
type of asynchronous rendering technology used, and this inconsistency can be confusing
to the end user. For example, with IFRAME technology each portlet interaction is tracked,
but this interaction does not update the “view” from the server’s perspective; if the user
clicks the Back button, the server takes the user to a state preceding the interaction with the
portlet.
z The initial (completion of) page load for an asynchronously rendered portlet page might be
slightly longer because, for example, loading five portlets entails six requests to the server.
However, since the page is starting to load, the user might perceive a faster load time even
if the completion takes more time overall.
z You should pre-define portlet sizes using Look & Feel settings; otherwise, as the page
z
A
loads, the portlets might resize several times as they adjust to their arrangement on the
page.
Portlet backing files are run twice: once for the outer request and another for the inner
(content) request. You can use the set of framework APIs in the PortletBackingContext
ET
class to distinguish between these two requests; for more information, refer to the Javadoc
information for these APIs:
com.bea.netuix.servlets.controls.portlet.PortletPresentationContext.isAsyncContent()
com.bea.netuix.servlets.controls.portlet.PortletPresentationContext.isContentOnly()
com.bea.netuix.servlets.controls.portlet.backing.PortletBackingContext.isAsyncContent()
com.bea.netuix.servlets.controls.portlet.backing.PortletBackingContext.isContentOnly()
B
z Asynchronous portlet rendering can be used with control tree optimization. Most of the
best practices for contol tree optimization also apply to the design of asynchronous
rendering. For more information on control tree optimization, refer to the Portal
Development Guide.
z Interportlet communication is not supported when asynchronous content rendering is

enabled; however, you can temporarily disable asynchronous rendering in specific
situations if needed. For details, refer to “Asynchronous Content Rendering and IPC” on
page 7-9.
z Using forked pre-rendering or forked rendering in an asynchronous portlet is not

recommended, and could result in unexpected behavior.

Considerations for IFRAME-based Aynchronous Rendering

Some special considerations associated with IFRAME-based asynchronous rendering include:
z IFRAME rendering varies depending on the browser. Making an IFRAME implementation

seamless to an end user involves several factors, such as proper skin/skeleton development
conventions, cross-browser development, and so on.
z If the content is larger than the IFRAME region, horizontal and/or vertical scrolling will be
enabled. Be careful of content which itself contains scrolling regions, as it can be difficult
to manipulate all scrolling regions to view all embedded content..
z IFRAME rendering might complicate other aspects of portal development, such as

cross-portlet drag and drop, which is used in the GroupSpace sample application.
z IFRAME rendering works whether or not Javascript is enabled.
A
Considerations for AJAX-based Asynchronous Rendering
Some special considerations associated with Asynchronous JavaScript and XML (AJAX)-based
asynchronous rendering include:
ET
z AJAX technology relies on Javascript. If users disable Javascript in their browser,
AJAX-based portlets will be broken (the content will never render).
z This mechanism might not be compatible with other AJAX mechanisms, such as those that
might typically be used by content authors to dynamically populate forms, for example.
Generally speaking, a best practice is to either let WebLogic Portal manage AJAX at the
portal level, or turn off AJAX for a portlet if you intend to incorporate AJAX behaviors
B
into your portlet.
z The current AJAX implementation does not support XHTML. The implementation
performs DOM operations that are known not to work in some browsers when using an
XHTML content type. This problem arises when a Look & Feel skeleton is configured to
use an XHTML content type.You can avoid this problem by doing one of two things:
– Use an HTML content type for the portal
– Use the IFRAME-based implementation of async portlet rendering

Comparing IFRAME- and AJAX-based Aynchronous

Rendering
Table 7-1 summarizes the advantages and disadvantages of IFRAME- and AJAX-based
asynchronous rendering. BEA recommends AJAX as a more robust implementation.
Table 7-1 IFRAME-based and AJAX-based Asynchronous Portlet Summary Table

IFRAME Works with Javascript enabled or Generally perceived as providing a less

disabled intuitive user experience.
Support for embedded media Can complicate more full-featured portlet
(non-HTML) files development tasks, such as cross-portlet drag
and drop.
Supports XHTML.
AJAX Generally perceived as providing a more

intuitive user experience.
A
Works only with Javascript enabled
Does not currently support XHTML
ET
Provides a single document for
full-featured portlet development tasks,
such as cross-portlet drag and drop.
Provides better Look & Feel integration
Portal Life Cycle Considerations with Asynchronous

B
Content Rendering
This section provides more information about life cycle and control tree implications associated
with using asynchronous content rendering.
For the initial request for a portal page, backing files attached to the portlet will run in the context
of a full portal control tree. However, portlet content—such as page flows, managed beans, JSP
pages, and so on—will not run.
The values for the above-referenced APIs will be:
PortletBackingContext.isAsyncContent() = true
PortletBackingContext.isContentOnly() = false
For the subsequent content requests, backing files attached to the portlet, and the portlet content
itself, will run in the context of a “dummy” control tree.

The values for the above-referenced APIs will be:

PortletBackingContext.isAsyncContent() = true
PortletBackingContext.isContentOnly() = true
PortletPresentationContext.isAsyncContent() = true
PortletPresentationContext.isContentOnly() = true
An important consequence of this model is that when asynchronous content rendering is enabled
for portlets, the portlet content will run in isolation from the rest of the portal. Such portlets
therefore cannot expect to have direct access to other portal controls such as books, pages,
desktops, other portlets, and so on.
Asynchronous Content Rendering and IPC

Although IPC is not supported when asynchronous content rendering is enabled, WebLogic
Portal provides some features that allow these two mechanisms to coexist in your portal
mechanisms described in this section.

A
environment. In addition, you can disable asynchronous rendering for single requests using the
Note: The techniques described in this section do not currently work with IFRAME portlets.
ET
File Upload Forms
For forms containing file upload mechanisms, the WebLogic Portal framework automatically
causes page refreshes without the need for any workarounds.
Disabling Asynchronous Rendering for a Single Interaction

Generally, if a portlet needs to disable asynchronous content rendering for a single interaction
B
(such as a form submission, link click, and so on), you should use the mechanism described here.
From a JSP page:
<render:controlContext asyncContentDisabled="true">
Form, anchor, etc. would appear here
(that is, <netui:form action=”submit”…)
</render:controlContext>
From Java code:
try {
AsyncContentControlContext.push(request).setAsyncContentDisabled(true);
// Code that generates a URL would appear here
} finally {

AsyncContentControlContext.pop(request)
}
URL Compression
URL compression interferes with some of the AJAX-specific mechanisms for page refreshes.
Because of this, URL compression must also be disabled whenever asynchronous content
rendering is disabled to force page refreshes. WebLogic Portal disables URL compression
automatically except when file upload forms are used; in this situation, you must explicitly
disable it. Use the following examples as a guide:
From a JSP page:
<render:controlContext urlCompressionDisabled="true">
Form, anchor, etc. would appear here
(that is, <netui:form action=”submit”…)
</render:controlContext>
From Java code:
try {
A
ET
UrlCompressionControlContext.push(request).setUrlCompressionDisabled(true)
;
// Code that generates a URL would appear here
} finally {
UrlCompressionControlContext.pop(request)
}
B
Backing Files
The most common means of managing portlet behavior within the control life cycle is to use a
portlet backing file. A portlet backing file can contain methods that correspond to portal control
life cycle stages, such as init() and preRender(). A portlet’s backing context, an abstraction of the
portlet control itself, can be used to manage the portlet’s characteristics. For example, in the init()
life cycle method, a request parameter might be evaluated, and depending on the parameter’s
value, the portlet backing context can be used to specify whether the portlet is visible or hidden.
Backing files allow you to programatically add functionality to a portlet by implementing (or
extending) a Java class, which enables preprocessing (for example, authentication) prior to
rendering the portal controls. Backing files work in conjunction with JSPs. The JSPs allow you
to code the presentation logic, while the backing files allow you to code simple business logic.

Backing Fil es
Backing files are always run before the JSPs. Backing files can be attached to portals either by
using Workshop for WebLogic or coding them directly into a .portlet file.
Backing files are simple Java classes that implement the
com.bea.netuix.servlets.controls.content.backing.JspBacking interface or extend
the com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking
interface abstract class. The methods on the interface mimic the controls life cycle methods (refer
to “How Backing Files are Executed” on page 7-11) and are invoked at the same time the controls
life cycle methods are invoked.
The following controls support backing files:
z Desktops
z Books
z Pages
z Portlets A
Both of the interportlet communication examples in Chapter 8, “Interportlet Communication”
use backing files.
ET
z How Backing Files are Executed
z Thread Safety with Backing Files
z Backing File Guidelines

B
z Adding a Backing File to a Portlet
How Backing Files are Executed

All backing files are executed before and after the JSP is called. In its life cycle, each backing file
calls these methods:
z init()
z handlePostBackData()
– raiseChangeEvents()
z preRender()
z dispose()

Figure 7-1 illustrates the life cycle of a backing file.
Figure 7-1 Backing File Life Cycle
On every request, the following occurs:

A
1. All init() methods are called on all backing files on an “in order” basis (that is, in the order
they appear in the tree). This method is called whether or not the control (the portal, page,
ET
book, or desktop) is on an active page.
2. Next, if the operation is a postback and the control (a portlet, page, or book) is on a visible
page, all handlePostbackData() methods are called. For example, if a portlet is on a page
but its parent page is not active, then this method is not called.
– If _nfpb="true" is set in the request parameter of any handlePostbackData()
methods called, raiseChangeEvents() is called. This method causes events to fire.
B
3. Next, all preRender() methods are called for all controls on an active (visible) page.
4. Next, the JSPs are called and rendered on the active page by the <render:beginRender>
JSP tag. Rendering is stopped with the <render:endRender> tag.
5. Finally, the dispose() method is called on the backing file.

If the backing file is part of a floated portlet, when that portlet is floated, only its contents are
executed.
If a book is embedded within a portlet, then the book would get called; however, if the book is
the parent of the portlet then it would not get called as it is not contained within the portlet.

Backing Fil es
Thread Safety with Backing Files

A new instance of a backing file is created per request, so you do not have to worry about thread
safety issues. New Java VMs are specially tuned for short-lived objects, so this is not the
performance issue it was in the past. Also, JspContent controls support a special type of backing
file that allows you to specify whether or not the backing file is thread safe. If this value is set to
true, only one instance of the backing file is created and shared across all requests.
Backing File Guidelines

As previously mentioned, a backing file must be an implementation of
com.bea.netuix.servlets.controls.content.backing.JspBacking interface or an
extension of the
com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking abstract
class. You only need to modify these files as necessary to implement the backing functionality
that you want.
A
Follow these guidelines when creating a backing file:
ET
z Ensure netuix_servlet.jar is included in the in the project classpath; otherwise,
compilation errors occur.
z When implementing the init() method, avoid any heavy processing.

Listing 7-1 is the backing file used in “IPC Example with Custom and Page Flow Event
Handlers” on page 8-17. In this example, the AbstractJspBacking class is extended to provide
the backing functionality required by the portlet.
B
Listing 7-1 Backing File Example
package backing;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;
import com.bea.netuix.events.Event;
import com.bea.netuix.events.CustomEvent;
import
com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking;

public class ListenCustomerName extends AbstractJspBacking

{
public void listenCustomerName( HttpServletRequest request,
HttpServletResponse response, Event event)
{
CustomEvent customEvent = (CustomEvent) event;
String message = (String) customEvent.getPayload();
HttpSession mySession = request.getSession();
mySession.setAttribute("customerName", message);
}
}
A
ET
Adding a Backing File to a Portlet
As a best practice, you should always store backing files in the web application’s
WEB-INF/src/backing directory, as the /src directory is the first place the application looks for
a backing file. If you are storing the first backing file for a web application, you need to create
B
the /backing directory under WEB-INF/src.
Adding the Backing File Using Workshop for WebLogic

You can add a backing file to a portlet either from within Workshop for WebLogic or by coding
it directly into the file to which you are attaching it. Simply specify the backing file in the
Backing File field of the Properties view, as shown in Figure 7-2. You need to specify the
backing directory and, following a dot-separator, only the backing file name. Do not include the
backing file extension; for example enter this:
backing.ListenCustomerName
Not this:
backing.ListenCustomerName.java

Backing Fil es
For the preceding example, if you include the file extension, the application interprets it as the
file name—because the file path is specified by a dot-separator—and looks for a non-existent file
called java in a non-existent directory called ListenCustomerName.
Figure 7-2 Adding a Backing File Using Workshop for WebLogic
Adding the Backing File Directly to the .portlet File

To add the backing file by coding it into a .portlet file, use the backingFile parameter within
A
the <netuix:jspContent> element, as shown in Listing 7-2.
Listing 7-2 Adding a Backing File to a .portlet File

ET
<netuix:content>
<netuix:jspContent
backingFile="portletToPortlet.pageFlowSelectionDisplayOnly.menu.
backing.MenuBacking"
contentUri="/portletToPortlet/pageFlowSelectionDisplayOnly/menu/
menu.jsp"/>
B
</netuix:content>

A
ET
B

CHAPTER 8
Interportlet Communication
A
Interportlet communication (IPC)—also called portlet-to-portlet communication—allows
multiple portlets to use or react to data. This feature is commonly used in self-service or sales
scenarios where common data elements, such as order ID or customer ID, are used across
multiple projects. Examples of IPC include:
ET
z A page flow portlet talks to another page flow portlet via the “Listen To” portlet property.
z A page flow portlet talks to a non-page flow portlet via the page flow’s outer request.
z A non-page flow portlet talks to another non-page flow portlet via the request.
z A non-page flow portlet talks to page flow portlet, using the ActionResolver class.
B
Portlet events can also carry payloads.

IPC in WebLogic Portal is based on the use of event handlers—Java objects that listen for
predefined events on other portlets in the portal and fire actions when that event occurs. You can
set up interportlet communication in two ways: using the Workshop for WebLogic interface, or
using the WebLogic Portal API. This chapter describes both methods.
This chapter includes two task-based examples of establishing interportlet communications. One
example uses an out-of-the-box portal event handler (“Basic IPC Example” on page 8-4), and the
other employs both a custom event handler and a page flow event handler (“IPC Example with
Custom and Page Flow Event Handlers” on page 8-17). These examples will familiarize you with
the event handlers and show you some of their common uses.

In ter p or tle t Co mmun ica ti on
These examples are specific to interportlet communications within a single portal web project.
They do not apply to federated portal projects. For information on establishing IPC with federated
portals (such as WSRP), refer to the BEA WebLogic Portal Federated Portals Guide.
z IPC with Multiple Web Projects and IFRAMEs-Examples
z IPC Special Considerations and Limitations
IPC with Multiple Web Projects and IFRAMEs-Examples

Before You Begin - Environment Setup
Before you use either of the interportlet communication procedure examples in this chapter, you
A
must have an existing portal development environment, consisting of a domain, Portal EAR
project, Portal Web project, Datasync project, and portal. To complete the pre-requisite tasks,
perform the tasks described in theGetting Started with WebLogic Portal tutorial, using the
information in Table 8-1 to enter the necessary values.
ET
1. Create a Portal domain (server).
2. Create a Portal EAR project.
3. Associate the EAR project with the server.
4. Create a Portal web project.

B
5. Create a Portal datasync project.
6. Create a portal.
Table 8-1 IPC Example - Environment Setup Values

Setup Information Notes/Values
Domain Configuration Wizard - Welcome Create a new WebLogic domain (the default)
Domain Configuration Wizard - In the Generate a domain configured automatically to

Select Domain Source support the following BEA products list, select
WebLogic Portal.
When you do this, other components are selected
automatically; keep all of them selected.

IPC with Multipl e Web Proj e c t s a nd I F R A ME s - Ex a m pl e s
Table 8-1 IPC Example - Environment Setup Values (Continued)

Setup Information Notes/Values
Domain Configuration Wizard - User name: weblogic

Configure Administrator Username and User password: weblogic
Password
Confirm user password: weblogic
Domain Configuration Wizard - Development Mode (the default)

Configure Server Start Mode and JDK JRockit SDK
Domain Configuration Wizard - No (the default)

Customize Environment and Services
Settings
Domain Configuration Wizard - Domain name: ipcDomain

Create WebLogic Domain
Portal EAR Project Wizard

A
Domain location: Accept the default, or specify another
directory on your system.
EAR Project Name: ipcEAR

ET
Switch to the Portal Perspective if you are not already
using it.
Servers view Right-click the server in the Servers view and select Add
and Remove Projects
Associate the ipcEAR project with the portal domain
ipcDomain.
B
Portal Web Project Wizard Web Project Name: ipcTestWebProject

In the Add project to an EAR checkbox: Check the box
and add to ipcEAR
Portal Datasync Project Wizard Datasync Project Name: ipcData

In the EAR Projects dialog, check the ipcEAR box.
Portal Wizard Right-click the ipcWebProject/WebContent

folder and select New > Portal
Portal Name: ipcPortal
Figure 8-1 shows how your workbench should look after you complete the pre-requisite tasks:

Figure 8-1 Workbench with Portal Perspective and Merged Projects View - Completed IPC Pre-Setup
A
ET
With a development environment set up, you can complete the steps described in either of these
B
sections:
z Basic IPC Example
z IPC Example with Custom and Page Flow Event Handlers

In these exercises, you create individual page flows, portlets, JSPs, and backing files to establish
interportlet communications within the portal project. You then add these portlets to a portal and
test the project to ensure that communication is successful.
Basic IPC Example

This section describes the process of setting up interportlet communications between two portlets
by using the Portal Event Handlers wizard in BEA WebLogic Workshop. This is a simple
example in which minimizing one portlet changes the text string in another portlet in the portal.

You should become familiar with the Portal Event Handlers Wizard and backing files before
attempting to replicate this example. For more information about the wizard, refer to “Portlet
Event Handlers Wizard Reference” on page 6-47. For more information on backing files, refer to
“Backing Files” on page 7-10.
This exercise is comprised of two main tasks:
1. Create the Portlets
2. Test the Project
Create the Portlets

In this section, you create two JSP files and the JSP portlets that surface these files. You also
create a backing file that contains the instructions necessary to complete the communication
between the two portlets, and you add an event handler to one of the portlets. After you have
A
created the portlets and attached the backing file, you test the project in your browser.
Note: Before continuing with this procedure, ensure that Workshop for WebLogic is running
and the ipcWebProject node is expanded.
ET
Create the JSP Files and Portlets
To create the JSP files that the portlets will surface, do the following:
1. Under the ipcWebProject node, double-click index.jsp.

index.jsp opens in the workbench editor, displaying the source code.
2. Replace the body text with the phrase Minimize Me! as shown in figure
B

Figure 8-2 index.jsp after Editing the Body Text in the Workbench Editor
3. Save the file as aPortlet.jsp

A
4. Right-click aPortlet.jsp in the Package Explorer view and select Generate Portlet from
the context menu.
ET
The Portal Details dialog appears (Figure 8-3). with aPortlet.jsp in the Content Path
field.
Figure 8-3 Portal Details Dialog Box for a Portlet

B
5. Select Minimizable and Maximizable and click Create.

aPortlet.portlet appears in the ipcWebProject/WebContent folder in the Package
Explorer view.

6. In the same directory, make a copy of aPortlet.jsp and give the name bPortlet.jsp to the
copy.
7. Open bPortlet.jsp in the workbench editor if it is not already open.

The XML code for the JSP file appears.
8. Copy the code from Listing 8-1 into the JSP, replacing everything from <netui:html>
through </netui:html>. This code displays event handling from the backing file that you
will create and attach in a subsequent step.
Listing 8-1 New JSP Code for bPortlet.jsp
<netui:html>
<% String event = (String)request.getAttribute("minimizeEvent");%>
<head>
<title>
Web Application Page
</title>
A
ET
</head>
<body>
<p>
Listening for portlet A minimize event:<%=event%>
</p>
</body>
</netui:html>
B
The source should look like the example in Figure 8-2.

Figure 8-2 Updated bPortlet JSP Source
A
ET
9. Save the file.
10. Following the same steps you used previously, generate a portlet from the bPortlet.jsp
file.
Checkpoint: At this point the ipcWebProject/WebContent folder contains these files:
aPortlet.jsp, aPortlet.portlet, bPortlet.jsp, and bPortlet.portlet.
B
Create the Backing File

To create the backing file, do the following:
1. In ipcWebProject, right-click the src folder and select New > Folder from the menu.
The Create New Folder dialog box appears.
2. Create a folder called backing.

The folder backing will appear under ipcWebProject/src, as shown in Figure 8-3.

Figure 8-3 New Backing File Folder in Package Explorer View
3. Right-click the backing folder and select New > Other.
4. In the New – Select a wizard dialog, select Java > Class, and click Next.
The New Java Class dialog appears.
A
5. In the Name field, enter Listening and click Finish.
ET
The new Java class appears in the editor.
6. Delete the default contents of Listening.java, and copy the code from Listing 8-2 into
Listening.java.
Listing 8-2 Backing File Code for listening.java

B
package backing;
import com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking;
public class Listening extends AbstractJspBacking
{
static final long serialVersionUID=1L;
private static boolean minimizeEventHandled = false;
public void handlePortalEvent(HttpServletRequest request,

HttpServletResponse response, Event event)

{
minimizeEventHandled = true;
}
public boolean preRender(HttpServletRequest request, HttpServletResponse

response)
{
if (minimizeEventHandled){
request.setAttribute("minimizeEvent","minimize event handled");

}else{
request.setAttribute("minimizeEvent",null);
}
// reset
minimizeEventHandled = false;
return true;
}
}
A
ET
The source should now look like that shown in Figure 8-4.
Figure 8-4 Listening.java with Updated Backing File Code

B

7. Save Listening.java.
Attach the Backing File

Now you will attach the backing file created in the previous section to bPortlet.portlet.
Perform the following steps:
1. In the Package Explorer, double-click bPortlet.portlet to open it.
2. Click on the portlet in the editor, if needed, to display the portlet’s properties. You should see
an orange border around the outside of the portlet, as shown in Figure 8-5.
Figure 8-5 bPortlet with Outer Border Selected to Display Properties
Click here to
display all
A properties
ET
B
Tip: The Properties view is a default view in the Portal perspective. If it is not visible,
select Window > Show View > Properties.
3. In the Properties view, enter backing.Listening into the Backable Properties > Portlet
Backing File field, as shown in Figure 8-6.

Figure 8-6 Attaching the Backing File in the Properties View
4. Save the file.
Add the Event Handler to bPortlet

You now add the event handler to bPortlet.portlet. This handler will be set up so that it will
event handler, perform the following steps: A

listen for an event on a specific portlet and fire an action in response to that event. To add the
Note: bPortlet.portlet should be displayed in the Workshop for WebLogic editor. If it

ET
isn’t, locate it in the producerWeb/WebContent folder in the application panel and
double-click it.
1. Click on the portlet in the editor if needed to display its properties.
1. In the Properties view, click in the Value field of the Event Handlers property. A button
lableled with an ellipses (...) appears, as shown in Figure 8-7.
B
Figure 8-7 Event Handlers Button
Event Handlers Button

2. Click the ellipses button (...) to bring up the Portlet Event Handlers dialog, as shown in
Figure 8-8.
Figure 8-8 Portlet Event Handlers Dialog Box
A
3. Click Add Handler to open the Event Handler drop-down list.
4. From the drop down list, select Handle Portal Event.

ET
The Portlet Event Handlers dialog box expands to allow entry of more details, as shown in
Figure 8-9.
Figure 8-9 Event Handler Dialog Box Expanded

B

5. Accept the defaults for all fields except Portlet.
6. In the Portlet field, click the ellipses button .

The Please Choose a File dialog appears.
7. Click aPortlet.portlet and click OK.

The dialog box closes and aPortlet_1 appears in the Listen to (portlets): list and in the
Portlet field, as shown in Figure 8-10. The label aPortlet_1 is the definition label of the
portlet to which the event handler will listen.
Figure 8-10 Adding portlet_1
A
ET
8. Click the Event drop-down control to open the list of portal events that the handler can listen
for and select onMinimize, as shown in Figure 8-11.
Figure 8-11 Event Drop-down List

B
9. Click Add Action to open the action drop-down list and select Invoke BackingFile Method.
10. Open the Method drop-down control and select handlePortalEvent, as shown in
Figure 8-12.

Figure 8-12 Adding the Backing File Method
11. Click OK.

The event handler is added. Note that the Value field of the Event Handlers property now
indicates 1 Event Handler.
Test the Project

A
Test the communication between your portlets by following these steps:
Note: Before you begin, ensure that all files are saved.
ET
1. Select ipcPortal.portal to display it in the workbench editor.
2. Drag both aPortlet.portlet and bPortlet.portlet from the Package Explorer view
onto the portal layout, as shown in Figure 8-13.
B

Figure 8-13 Portal Layout with aPortlet and bPortlet Added
A
ET
3. Save the portal.
4. Run the portal. To do this, right-click ipcPortal.portal in the Package Explorer view and
select Run As > Run on Server.
5. At the Run On Server – Define a New Server dialog, click Finish.

The portal will render in your browser (Figure 8-14).
B
Figure 8-14 ipcLocal Portal in Browser
6. Click the minimize button to minimize aPortlet.

Note the content change in bPortlet.

I PC Spe cial Considerat i o n s a n d L i m i t at i o n s
Figure 8-15 ipcPortal Showing the Effect of Minimizing aPortlet
Portlet text changed
Summary
In this example, you set up your environment and you added two JSP portlets built on the local
portal. One portlet, aPortlet, was fairly simple, while the second portlet, bPortlet, surfaced a more
complex JSP file, used a backing file, and contained a portal event handler. When you tested the
communication between the portlets, you observed how the bPortlet changed when an event
occurred on aPortlet. This is called local interportlet communication.
A
IPC Example with Custom and Page Flow Event Handlers
TBD
ET
IPC Special Considerations and Limitations
The following sections describe special considerations that you should keep in mind as you
implement interportlet communications.
B
z Using Asynchronous Portlet Rendering with IPC
z Generic Event Handler for WSRP
z Consistency of the Listen To Field
z Using a Session Attribute Instead of Request Attribute
Using Asynchronous Portlet Rendering with IPC

The use of IPC with asynchronous portlet rendering is not supported. However, WebLogic Portal
provides some features that allow these two mechanisms to coexist in your portal environment.
In certain cases, you must explicitly disable asynchronous rendering or URL compression.
For more information, refer to “Asynchronous Content Rendering and IPC” on page 7-9.

Generic Event Handler for WSRP

Use a generic event handler to work with WebLogic Portal WSRP. To do this, first select Generic
Event Handler, then select Add Action and select Window Mode|State. Then manually type in
the event name—for example, onMinimize.
Consistency of the Listen To Field

Pay attention to the Listen To field when you set up the listener portlet. The portlet definition you
use on the consumer must match the WSRP portlet's portlet definition. For example, if you have
"portlet_2" listening to "portlet_1", the WSRP corresponding to "portlet_1"—the proxy on the
consumer—must also have its portlet definition label set to "portlet_1". For more information on
using IPC with WSRP, refer to the Federation Guide.
Using a Session Attribute Instead of Request Attribute

A
The example in this chapter uses a Request attribute to hold the text string that indicates whether
the event was received or not. Occasionally this method can appear to cause problems because of
Request scoping in WebLogic Portal (inner requests compared to outer requests). In some cases,
ET
you should use the Session object to hold this string. The following example shows how the
backing file would look in this case:
Listing 8-1 Backing File Using a Session Attribute
package backing;
B
import
com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking;
import com.bea.netuix.events.GenericEvent;
import com.pointbase.session.session;
import javax.servlet.http.HttpSession;
public class Listener extends AbstractJspBacking
{
private static boolean minimizeEventHandled = false;
public void handlePortalEvent
{

I PC Spe cial Considerat i o n s a n d L i m i t at i o n s
HttpServletRequest request,
HttpServletResponse response,
Event event
}
{
System.out.println ( "backing.Listener: EVENT RECVD" );
minimizeEventHandled = true;
}
public boolean preRender{HttpServletRequest request,
HttpServletResponse response
}
{
{ A
HttpSession sesh = request.getSession(); if (minimizeEventHandled)
sesh.setAttribute("miniMe_EVENT","minimize event handled");

ET
}
else
{
sesh.setAttribute("miniMe_EVENT", "event NOT handled");
}
// reset
B
minimizeEventHandled = false;
return true;
}
}

A
ET
B

Part III Staging
A
BEA recommends that you deploy your portal, including portlets, to a staging environment,
where it can be assembled and tested before going live. In the staging environment, you use the
WebLogic Portal Administration Console to assemble and configure desktops. You also test your
portal in a staging environment before propagating it to a live production system.
ET
B
Part III includes the following chapters:
z Chapter 9, “Assembling Portlets into Desktops”
z Chapter 10, “Deploying Portlets”

A
ET
B

CHAPTER 9
Assembling Portlets into Desktops
Note:
A
Most of this chapter has not been updated to reflect the Version 9.2 interface.
You perform the tasks described in this chapter to prepare the individual portlets that are part of
your portal application for public consumption. After you add portlets to desktops, you can
configure and test the application as a whole, and then deploy it to the production environment
ET
when it is ready for public access.
Before you perform the tasks described in this chapter, use the Portal Development Guide to
create the framework into which you will add the portlets— this includes the portal and its menus,
layouts, the Look & Feel components for the overall portal, and the framework of the actual
desktop. You also must have already created the set of portlets, also called the portlet library,
from which you will choose the portlets to add to the desktop.
B
The primary tools used in this chapter are the WebLogic Portal Administration Console, the
WebLogic Portal Propagation Utility (to move database and LDAP data between staging,
development, and production), WebLogic Server application deployment tools, and any external
content or security providers that you are using.
z Portlet Library
z Adding, Arranging, and Deleting Portlets on the Desktop
z Customizing Portlet Properties and Behavior

As sembling Portl ets into Desk to ps
Portlet Library
TBD - describes how the portlets created using Workshop for WebLogic appear in the Library
folder in the WebLogic Portal Administration Console.
Portlets in the Library Compared with Portlets on the

Desktop (decoupling)
TBD
Adding, Arranging, and Deleting Portlets on the Desktop

TBD
Add a Portlet to a Page in the Staging Environment

TBD A
ET
Move a Portlet on a Page
This section is currently a copy of a related task from the getting Started with WebLogic Portal
tutorials; it will be updated for GA.
In this task you view the portlets for a page—the portlets that you created using Workshop for
WebLogic—and rearrange them. Then you will view your work.
To update your desktop page, follow these steps:
B
1. In the Portal Resources tree for myPortalWebProject, expand the tree to display the pages for
the desktop, as shown in Figure 11-16.

A dd i n g, Ar r an gi n g, an d D e l e t i n g P o r t l e t s o n t he D e s k to p
Figure 11-16 Expanded Portal Resources Tree Showing Desktop Pages
2. Click Page 1 to select it.
A
The Page 1 details display in the right pane of the Administration Console, as shown in
Figure 11-17.
ET
Figure 11-17 Page 1 Edit Contents Tab
B
3. Drag the BEA Browser Portlet into the same Placeholder as the Simple JSP Portlet, as shown
in Figure 11-18.

Figure 11-18 Moving the BEA Browser Portlet by Dragging
Figure 11-19.
4. Click Save Changes.

A
When you release the portlet, it displays above the Simple JSP Portlet, as shown in
ET
Figure 11-19 Result After Moving the BEA Browser Portlet in the Administration Console
B
5. In the Portal Resources tree, click myDesktop to display the Details page.
6. Click View Desktop.

Customizing Portlet Pro perties and Be havior
The desktop displays in a browser, with the portlets in their new positions, as shown in
Figure 11-20.
Figure 11-20 Desktop in Browser Showing Moved Portlets
Customizing Portlet Properties and Behavior

TBD A
ET
Modify Portlet Properties in a Staging Environment
TBD
B

A
ET
B

C H A P T E R 10
Deploying Portlets
This chapter TBD

A
This chapter describes the tasks associated with deploying portlets from the staging environment
to the production environment when they are ready for public access.
ET
The primary tools you use to perform the tasks described in this chapter are the WebLogic Portal
Propagation Utility and WebLogic Server application deployment tools. In cases where external
content or security providers affect how you perform a particular task, this guide will make
recommendations for those cases wherever possible.
Deploying a New Portlet into a Production Portal

B
TBD

Depl oyin g P or tl et s
A
ET
B

Part IV Production
A
A production portal is live and available to end users. A portal in production can be modified by
administrators using the WebLogic Portal Administration Console and by users using Visitor
Tools. For instance, an administrator might add additional portlets to a portal or reorganize the
contents of a portal.
ET
.
B
Part IV includes the following chapter:
z Chapter 11, “Managing Portlets in Production”

A
ET
B

C H A P T E R 11
Managing Portlets in Production
This chapter TBD

A
Transferring Changes from Production Back to
Development
ET
TBD
B

Ma na gi ng Po rt let s in Pr od uct io n
A
ET
B

Portlets

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Portlets

Uploaded by

Copyright:

Available Formats

BEA WebLogic

Version 9.2 BETA

Restricted Rights Legend

Trademarks and Service Marks

Database Structure for Portlet Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

BEA WebLogic Portal Portlet Development Guide iii

Part II. Development

Types of Database Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

iv BEA WebLogic Portal Portlet Development Guide

Struts Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26

6. Refining and Testing Portlets

BEA WebLogic Portal Portlet Development Guide v

Portlet Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-44

vi BEA WebLogic Portal Portlet Development Guide

Adding a Backing File to a Portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14

BEA WebLogic Portal Portlet Development Guide vii

Part III. Staging

Part IV. Production

Transferring Changes from Production Back to Development . . . . . . . . . . . . . . . . . . . . 13-1

viii BEA WebLogic Portal Portlet Development Guide

This chapter includes the following sections:

BEA WebLogic Portal Portlet Development Guide 1-1

Figure 1-1 Sample Portlet in Workshop for WebLogic

Figure 1-2 Sample Portlet as Displayed in a Web Page

“Portlet Types” on page 3-1.

Portlet Development and the Portal Life Cycle

1-2 BEA WebLogic Portal Portlet Development Guide

z Chapter 2, “Portlet Planning”

z Chapter 3, “Portlet Types”

BEA WebLogic Portal Portlet Development Guide 1-3

z Chapter 4, “Understanding Portlet Development”

z Chapter 5, “Building Portlets”

z Chapter 6, “Refining and Testing Portlets”

z Chapter 7, “Optimizing Portlet Performance”

z Chapter 8, “Interportlet Communication”

z Chapter 9, “Assembling Portlets into Desktops”

z Chapter 10, “Deploying Portlets”

z Chapter 11, “Managing Portlets in Production”

1-4 BEA WebLogic Portal Portlet Development Guide

z BEA WebLogic Portal Architecture Guide

z BEA WebLogic Portal Overview

z BEA WebLogic Portal Portal Development Guide

BEA WebLogic Portal Portlet Development Guide 1-5

1-6 BEA WebLogic Portal Portlet Development Guide

Part I includes the following chapters:

z Chapter 2, “Portlet Planning”

z Chapter 3, “Portlet Types”

BEA WebLogic Portal Portlet Development Guide

2-2 BEA WebLogic Portal Portlet Development Guide

This chapter includes the following sections:

z Database Structure for Portlet Data

z Portlet Development in a Distributed Portal Team

z Portlets in a Non-Portal Environment

z Planning Portlet Instances

BEA WebLogic Portal Portlet Development Guide 2-1

Database Structure for Portlet Data

z Primary – Properties defined in development and stored in the .portlet file.

z User – User-customized instances of the portlet defined in the Visitor Tools.

2-2 BEA WebLogic Portal Portlet Development Guide

Removing Portlets from Production

Portlet Development in a Distributed Portal Team

Portlets in a Non-Portal Environment

BEA WebLogic Portal Portlet Development Guide 2-3

z Session information is not retained - TBD